dds/networks.rkt

#lang racket

;;; dds/networks

;;; This module provides some quick definitions for and analysing
;;; network models.  A network is a set of variables which are updated
;;; according to their corresponding update functions.  The variables
;;; to be updated at each step are given by the mode.
;;;
;;; This model can generalise Boolean networks, TBANs, multivalued
;;; networks, etc.

(require "utils.rkt" graph)

(provide
 ;; Functions
 (contract-out [update (-> network? state? (listof variable?) state?)]
               [make-state (-> (listof (cons/c symbol? any/c)) state?)]
               [make-network-from-functions (-> (listof (cons/c symbol? update-function/c)) network?)]
               [update-function-form->update-function (-> update-function-form? update-function/c)]
               [network-form->network (-> network-form? network?)]
               [make-network-from-forms (-> (listof (cons/c symbol? update-function-form?))
                                            network?)]
               [list-interactions (-> network-form? variable? (listof variable?))]
               [build-interaction-graph (-> network-form? graph?)]
               [build-all-states (-> (listof (cons/c variable? generic-set?)) (listof state?))]
               [build-all-states-same-domain (-> (listof variable?) generic-set? (listof state?))])
 ;; Predicates
 (contract-out [variable? (-> any/c boolean?)]
               [state? (-> any/c boolean?)]
               [update-function-form? (-> any/c boolean?)]
               [network-form? (-> any/c boolean?)])
 ;; Contracts
 (contract-out [state/c contract?]
               [network/c contract?]
               [update-function/c contract?])
 ;; Syntax
 st nn)


;;; =================
;;; Basic definitions
;;; =================

(define variable? symbol?)

;;; A state of a network is a mapping from the variables of the
;;; network to their values.
(define state? variable-mapping?)
(define state/c (flat-named-contract 'state state?))

;;; An update function is a function computing a value from the given
;;; state.
(define update-function/c (-> state? any/c))

;;; A network is a mapping from its variables to its update functions.
(define network? variable-mapping?)
(define network/c (flat-named-contract 'network network?))

;;; Given a state s updates all the variables from xs.  This
;;; corresponds to a parallel mode.
(define (update bn  ; the Boolean network
                s   ; the state to operate on
                xs) ; the variables to update
  (let ([new-s (hash-copy s)])
    (for ([x xs])
      (let ([f (hash-ref bn x)])
        (hash-set! new-s x (f s))))
    new-s))

;;; A version of make-hash restricted to creating network states (see
;;; contract).
(define (make-state mappings) (make-immutable-hash mappings))

;;; A shortcut for make-state.
(define-syntax-rule (st mappings) (make-state mappings))

;;; A version of make-hash restricted to creating networks.
(define (make-network-from-functions funcs) (make-hash funcs))


;;; =================================
;;; Syntactic description of networks
;;; =================================

;;; An update function form is any form which can appear as a body of
;;; a function and which can be evaluated with eval.  For example,
;;; '(and x y (not z)) or '(+ 1 a (- b 10)).
(define update-function-form? any/c)

;;; A Boolean network form is a mapping from its variables to the
;;; forms of their update functions.
(define network-form? variable-mapping?)

;;; Build an update function from an update function form.
(define (update-function-form->update-function form)
  (λ (s) (eval-with s form)))

;;; Build a network from a network form.
(define (network-form->network bnf)
  (make-hash
   (hash-map bnf (λ (x form)
                   (cons x (update-function-form->update-function form))))))

;;; Build a network from a list of pairs of forms of update functions.
(define (make-network-from-forms forms)
  (network-form->network (make-hash forms)))

;;; A shortcut for make-network-from-forms.
(define-syntax-rule (nn forms) (make-network-from-forms forms))


;;; ============================
;;; Inferring interaction graphs
;;; ============================

;;; I allow any syntactic forms in definitions of Boolean functions.
;;; I can still find out which Boolean variables appear in those
;;; syntactic form, but I have no reliable syntactic means of finding
;;; out what kind of action do they have (inhibition or activation)
;;; since I cannot do Boolean minimisation (e.g., I cannot rely on not
;;; appearing before a variable, since (not (not a)) is equivalent
;;; to a).  On the other hand, going through all Boolean states is
;;; quite resource-consuming and thus not always useful.
;;;
;;; In this section I provide inference of both unsigned and signed
;;; interaction graphs, but since the inference of signed interaction
;;; graphs is based on analysing the dynamics of the networks, it may
;;; be quite resource-consuming.

;;; Lists the variables of the network form appearing in the update
;;; function form for x.
(define (list-interactions nf x)
  (set-intersect
   (extract-symbols (hash-ref nf x))
   (hash-keys nf)))

;;; Builds the graph in which the vertices are the variables of a
;;; given network, and which contains an arrow from a to b whenever a
;;; appears in (list-interactions a).
(define (build-interaction-graph n)
  (transpose
   (unweighted-graph/adj
    (hash-map n (λ (var _)
                  (cons var (list-interactions n var)))))))

;;; Given a list of pairs mapping variables to generic sets of their
;;; possible values, constructs the list of all possible states.
(define (build-all-states vars-domains)
  (let ([vars (map car vars-domains)]
        [domains (map cdr vars-domains)])
    (for/list ([s (apply cartesian-product domains)])
      (make-state (for/list ([var vars] [val s])
                    (cons var val))))))

;;; Given a list of variables and a domain common to all of them,
;;; builds the list of all possible states.
(define (build-all-states-same-domain vars domain)
  (build-all-states (for/list ([v vars]) (cons v domain))))