dds/scribblings/tbn.scrbl

#lang scribble/manual
@(require scribble/example racket/sandbox
	  (for-label typed/racket/base
	  	     (submod "../tbn.rkt" typed)
		     "../networks.rkt"
		     "../utils.rkt"
		     "../functions.rkt"
		     "../dynamics.rkt"))

@(define tbn-evaluator
  (parameterize ([sandbox-output 'string]
  		 [sandbox-error-output 'string]
		 [sandbox-memory-limit 500])
   (make-evaluator 'typed/racket #:requires '((submod "tbn.rkt" typed)))))

@(define-syntax-rule (ex . args)
  (examples #:eval tbn-evaluator . args))

@(define-syntax-rule (deftypeform . args)
  (defform #:kind "type" . args))

@(define-syntax-rule (deftype . args)
  (defidform #:kind "type" . args))

@title[#:tag "tbn"]{dds/tbn: Threshold and Sign Boolean Networks (TBN and SBN)}

@defmodule[(submod dds/tbn typed)]

@section{TBFs and states}

This module defines threshold Boolean networks (TBN), as well as sign
Boolean networks (SBN).  The update functions in such networks are
respectively @seclink["tbf" #:doc '(lib
"dds/scribblings/dds.scrbl")]{threshold Boolean functions} and sign
Boolean functions.

@defproc[(apply-tbf-to-state [a-tbf TBF] [st (State (U Zero One))])
			     (U Zero One)]{

Applies a TBF to a state.

The values of the variables of the state are ordered by
@racket[hash-map] and fed to the TBF in order.  The number of the
inputs of the TBF must match the number of variables in the state.

@ex[
(require "functions.rkt")
(apply-tbf-to-state (tbf #(1 1) 1) (hash 'x1 0 'x2 1))
]}

@defstruct*[tbf/state ([weights (VariableMapping Real)]
		       [threshold Real])]{

A state TBF is a @racket[TBF] with named inputs.  A state TBF can be
applied to states in an unambiguous ways.

}

@deftype[TBF/State]{

The type of the instances of @racket[tbf/state].

}

@deftogether[(@defproc[(tbf/state-w [tbfs TBF/State]) (VariableMapping Real)]
	      @defproc[(tbf/state-θ [tbfs TBF/State]) Real])]{

Shorter synonyms for field accessors of @racket[tbf/state].

@ex[
(let ([tbfs (tbf/state (hash 'a 1 'b 1) 1)])
  (values (tbf/state-w tbfs)
          (tbf/state-θ tbfs)))
]}

@defproc[(make-tbf/state [pairs (Listof (Pairof Variable Real))]
			 [threshold Real])
			 TBF/State]{

Makes a @racket[TBF/State] from a list of pairs of names of variables
and weights, as well as a threshold.

@ex[
(make-tbf/state '((x1 . 1) (x2 . 1)) 1)
]}

@defproc[(sbf/state? [tbfs TBF/State]) Boolean]{

A state sign Boolean function (SBF) is a @racket[TBF/State] whose
threshold is 0.

@ex[
(sbf/state? (tbf/state (hash 'a -1 'b 1) 0))
(sbf/state? (tbf/state (hash 'a -1 'b 1) 1))
]}

@defproc[(apply-tbf/state [tbfs TBF/State]
			  [st (State (U Zero One))])
			  (U Zero One)]{

Applies a @racket[TBF/State] to its inputs given by the state
@racket[st].

Applying a TBF consists in multiplying the weights by the
corresponding inputs and comparing the sum of the products to
the threshold.

This function is similar to @racket[apply-tbf], but because it applies
a @racket[TBF/State] to a @racket[(State (U Zero One))], it avoids
potential mismatches between weights and the corresponding
input values.

@ex[
(apply-tbf/state (tbf/state (hash 'a 2 'b -2) 1)
                 (hash 'a 1 'b 0 'c 1))
]}

@section{Reading TBFs and SBFs}

@defproc[(lists+vars->tbfs/state [vars (Listof Variable)]
				 [lsts (Listof (Listof Real))])
				 (Listof TBF/State)]{

Reads a list of @racket[TBF/State] from a list of list of
@racket[Real]s.

The last element of each list is taken to be the threshold of the
TBFs, and the rest of the elements are taken to be the weights.

@ex[
(lists+vars->tbfs/state '(x y) '((1 2 3) (1 1 2)))
]}

@defproc[(lists+headers->tbfs/state [lsts+headers (Pairof (Listof Variable) (Listof (Listof Real)))])
				    (Listof TBF/State)]{

Like @racket[lists+vars->tbfs/state], but the names of the variables
are taken from the first line of @racket[lsts+headers].

All the lines in @racket[lsts+headers] are assumed to be of the same
lenght, which means in particular that the last element of the first
line (the threshold column) is discarded.

@ex[
(lists+headers->tbfs/state '((x y f) (1 2 3) (1 1 2)))
]}

@defproc[(lists->tbfs/state [lsts (Listof (Liostf Real))])
			    (Listof TBF/State)]{

Like @racket[lists+vars->tbfs/state], but the names of the variables
are generated as @tt{xi}, where @italic{i} is the index of the
variable, starting from 0.

@ex[
(lists->tbfs/state '((1 2 3) (1 1 2)))
]}

@deftogether[(@defproc[(lists+vars->sbfs/state [vars (Listof Variable)]
					       [lsts (Listof (Listof Real))])
					       (Listof TBF/State)]
	      @defproc[(lists+headers->sbfs/state
			[lsts (Pairof (Listof Variable) (Listof (Listof Real)))])
			(Listof TBF/State)]
	      @defproc[(lists->sbfs/state [lsts (Listof (Listof Real))])
	      				 (Listof TBF/State)])]{

Like the corresponding TBF-related functions, but which create SBFs.
In other words, the input lists are treated as lists of weights, and
the thresholds are set to 0.

@ex[
(lists+vars->sbfs/state '(x y) '((1 2) (1 1)))
(lists+headers->sbfs/state '((x y) (1 2) (1 1)))
(lists->sbfs/state '((1 2) (1 1)))
]}

@defproc[(read-org-tbfs/state [str String]) (Listof TBF/State)]{

Reads a list of @racket[TBF/State] from an Org-mode string containing
a sexp, containing a list of lists of numbers.  As in
@racket[lists->tbfs/state], the last element of each list is taken to
be the threshold of the TBF, and the rest of the elements are taken to
be the weights.

Similarly to @racket[lists->tbfs/state], the names of the variables
are generated as @tt{xi}, where @italic{i} is the index of the
variable, starting from 0.

@ex[
(read-org-tbfs/state "((1 2 3) (1 1 2))")
]}

@defproc[(read-org-tbfs/state+headers [str String]) (Listof TBF/State)]{

Like @racket[read-org-tbfs/state], but the first list in @racket[str]
is taken to contain the names of the variables, similarly to
@racket[lists+headers->tbfs/state].

@ex[
(read-org-tbfs/state+headers "((a b f) (1 2 3) (1 1 2))")
]}