BooN’s Documentation
The BooN project provides a complete set of functionalities for Boolean Network (BooN) analysis. It was originally designed to explore the modeling of genetic networks by Boolean networks. The project includes:
the definition of a Boolean network with the possibility to load and save it;
the computation of the model of dynamics with respect to a mode policy;
the definition of the interaction graph including a modular decomposition of the interaction;
the computation of equilibria based on dynamics model;
the efficient symbolic computation of stable states based on SAT solver;
the controllability analysis predicting which variables must be frozen to reach the expected goal at stable states based on possibility and necessity query;
also different basic functionalities are included as: update formula and importing/exporting to a text or SBML file the Boolean network.
BooN Modules Description
The BooN project comprises 3 modules:
boon
module is related to the manipulation of Boolean network named BooN which is an object.boon.logic
sub module includes the basic functions on propositional formula, as well as more advanced features like fast CNF conversion for large formulas, CNF conversion using Tseitin’s method, and prime implicant calculation. These functions are used in the BooN modules.boonify
module is the graphical interface manipulating BooN:computation of dynamical model for synchronous and asynchronous mode, the computation ot the stable states, and the controllability analysis. For exploring BooN interactively runboonify.py
BooN installation
Go in the directory of BooN and type:
pip install .
or,
python -m pip install .
Function Description
Boon Module
This module contains functions used for the manipulation of Boolean network (BooN). BooN is the class of this module.
- class boon.BooN(descriptor=None, style={'type': 'infix', And: '∧', Equivalent: '⇔', False: 'false', Implies: '⇒', Not: '¬', Or: '∨', True: 'true', Xor: '⊻'}, pos: dict = {})[source]
Boolean Network Class.
- Parameters:
desc (Dict) – Boolean network descriptor { variable: formula, …}.
style (dict) – Output form of the BooN: LOGICAL, SYMPY, MATHEMATICA, JAVA, BOOLNET, …,
pos (dict) – the positions of the nodes in the interaction graph. {node:position, …}.
- cnf(variable: Symbol | None = None, simplify: bool = True, force: bool = True) BooN [source]
Convert the formulas of the Boolean network to CNF.Convert the formulas of the Boolean network to CNF.
- Parameters:
variable (Symbol) – The variable where the formula is to be converted in CNF (Default None). If variable is None, then all the formulas are converted to CNF.
simplify (bool) – Boolean flag determining whether the formula should be simplified (Default True).
force (bool) – Boolean flag forcing the complete simplification of the resulting CNF (Default True).
- Returns:
self
- Return type:
- control(frozenfalse: set | list | frozenset, frozentrue: set | list | frozenset) None [source]
Set control on the BooN. The controlled variables are divided in two classes: the variables frozen to false and the variables frozen to true. A variable can be in both classes.
- Parameters:
frozenfalse (Iterable object (list, set, tuple)) – List, set or sequence of variables that should be frozen to false by control.
frozentrue (iterable object (list, set, tuple)) – List, set or sequence of variables that should be frozen to true by control.
- Returns:
self
- Return type:
- delete(variable) BooN [source]
Delete a variable in a BooN. The formulas must all be in DNF to properly delete the variable.
- Parameters:
variable (Symbol) – The variable to delete.
- Returns:
self
- Return type:
- static destify(query, trace: bool = False, solver=<class 'pulp.apis.coin_api.PULP_CBC_CMD'>)[source]
Compute the core which is the minimal set of controls under the inclusion to satisfy the query at stable state. Destify is a neologism that refers to the deliberate and purposeful act of shaping destiny by influencing or directing the course of events or outcomes towards an expected goal.
- Parameters:
query (Sympy formula) – The query defining the expected destiny or goal as propositional formula.
trace (bool) – Boolean flag determining whether the trace is activated (Default: False).
solver (type) – The PulpSolver used for solving the problem (Default: PULP_CBC_CMD).
- Returns:
the core of control
- Return type:
frozenset[sympy formula]
- dnf(variable: Symbol | None = None, simplify: bool = True, force: bool = True) BooN [source]
Convert formula(s) of the Boolean network to DNF. :param variable: The variable where the formula is to be converted in DNF (Default: None). If variable is None, then all the formulas are converted to DNF. :param simplify: Boolean flag determining whether the formula should be simplified (Default: True). :param force: Boolean flag forcing the complete simplification (Default: True). :type variable: Symbol :type simplify: bool :type force: bool :return: self :rtype: BooN
- draw_IG(IG: DiGraph | None = None, modular: bool = False, **kwargs) DiGraph [source]
Draw the interaction graph. :param IG: The interaction graph or None. If None, the interaction graph is generated from BooN (Default: None). :param modular: Boolean indicating whether the modular structure of interactions is displayed if True (Default: False) :param kwargs: additional keyword arguments to pass to the interaction graph drawing :type IG: networkx DiGraph :type modular: bool :type kwargs: dict :return: interaction graph :rtype: Networkx DiGraph
- draw_model(model: ~networkx.classes.digraph.DiGraph | None = None, mode: ~collections.abc.Callable = <function asynchronous>, color: list[str] = ['gold', 'tomato', 'yellowgreen', 'plum', 'mediumaquamarine', 'darkorange', 'darkkhaki', 'forestgreen', 'salmon', 'lightcoral', 'cornflowerblue', 'orange', 'paleviolet', 'coral', 'dodgerblue', 'yellowgreen', 'orangered', 'pink', 'blueviolet', 'crimson'], **kwargs) None [source]
Draw the graph representing the datamodel of dynamics.
- Parameters:
model – Input datamodel graph of the BooN or None (Default: None).
If it is None, the asynchronous datamodel computed from the BooN. :param mode: Function characterizing the mode of the datamodel (Default: asynchronous) :param color: list of colors for highlighting the equlibria (Default: COLOR) :param kwargs: extra parameters of nx.draw_networkx. :type model: Networkx DiGraph :type mode: function :type color: list :type kwargs: dict :return: None :rtype: None
- equilibria(model: ~networkx.classes.digraph.DiGraph | None, mode: ~collections.abc.Callable = <function asynchronous>) list[list] [source]
Calculate equilibria for the network based on datamodel dynamics. The method examines an exponential number of states, and thus it is restricted to networks with a small number of variables (max. ~10).
- Parameters:
model – Data model from which the equilibria are calculated.
If the datamodel is None, then the datamodel will be calculated from BooN. (Default: None) :param mode: updating mode function, used if the datamodel is None (Default: asynchronous). :type model: Networkx DiGraph :type mode: function :return: Equilibria structure as a list of lists where each sublist is an attractor. :rtype: List[list]
- from_ig(IG: nx.DiGraph) Boon [source]
Define the descriptor of a BooN from an interaction graph.
- Parameters:
IG – Interaction graph.
- Returns:
self
- Return type:
- from_sbmlfile(filename: str) BooN [source]
Import the Boolean network from a sbml file. :param filename: The file name to import the Boolean network. If the extension is missing, then .sbml is added. :type filename: str :return: self :rtype: BooN
- from_textfile(filename: str, sep: str = '\n', assign: str = ',', ops: dict = {'type': 'normal form', And: '&', False: '0', Not: '!', Or: '|', True: '1'}) BooN [source]
Import the Boolean network from a text file. The syntax depends on the ops’ descriptor. The formulas must be in normal form containing OR, AND, NOT operators only. The nodes are circularly mapped. :param filename: The file name to import the Boolean network. If the file extension is missing, then .txt is added. :param sep: The separator between definitions (default BOONSEP constant) :param assign: the operator defining the formula for a variable, e.g., a = f(…) → assign is ‘=’ (Default: ‘,’). :param ops: A dictionary stipulating how the operators And, Or, Not are syntactically written (Default: BOOLNET). :type filename: Str :type sep: str :type assign: str :type ops: dict :return: self :rtype: BooN
- property interaction_graph: DiGraph
Build the interaction graph.
- Returns:
The interaction graph.
- Return type:
Networkx DiGraph
- load(filename: str) BooN [source]
Load the Boolean Network from a file. If the extension is missing, then .boon is added.
- Parameters:
filename (Str) – The name of the file to load the network.
- Returns:
self
- Return type:
- model(mode: ~collections.abc.Callable = <function asynchronous>, self_loop: bool = False) DiGraph [source]
Compute the dynamical datamodel of the BooN w.r.t. a mode.
- Parameters:
self_loop (Bool) – Determines whether the boon loops are included in the datamodel (Default: False).
mode (function) – Determines the mode policy applied to the datamodel (Default: asynchronous).
- Returns:
a Digraph representing the complete state-based dynamics.
- Return type:
Networkx Digraph
- necessary(query, trace: bool = False)[source]
Compute the necessary constraints.
- Parameters:
query (Sympy formula) – A formula characterizing the query, objective or goal.
trace (bool) – Boolean flag determining whether the trace is activated (Default value = False).
- Returns:
CNF specifying the necessity.
- Return type:
Sympy formula
- possibly(query)[source]
Compute the possibility constraint.
- Parameters:
query (Sympy formula) – A formula characterizing the query, objective or goal.
- Returns:
a formula specifying the possibility.
- Return type:
Sympy formula
- rename(source: Symbol, target: Symbol) BooN [source]
Rename a variable.
- Parameters:
source (Symbol) – The variable to rename.
target (Symbol) – The variable renaming the source.
- save(filename: str = 'BooN17-sept.-24-18.boon') None [source]
Save the Boolean Network to file. If the extension is missing, then .boon is added.
- Parameters:
filename (str) – The name of the file to save the network (Default: BooN+date+hour.boon)
- Returns:
None
- Return type:
None
- property stable_states: list[dict]
Compute all the stable states of a BooN. The algorithm is based on SAT solver.
- Returns:
List of stable states.
- Return type:
List[dict]
- str(sep: str = '\n', assign: str = '=') str [source]
Return a string representing the BooN. The output format can be parameterized (see style argument of BooN) :param sep: the separator between formulas (default BOONSEP constant) :param assign: the operator defining the assignment of a formula to a variable (e.g., a = f(…) → assign is ‘=’). (Default: ‘=’) :type sep: str :type assign: str
- to_textfile(filename: str, sep: str = '\n', assign: str = ',', ops: dict = {'type': 'normal form', And: '&', False: '0', Not: '!', Or: '|', True: '1'}) BooN [source]
Export the Boolean network in a text file. If the file extension is missing, then .txt is added. The default format is BOOLNET.
- Parameters:
filename – The file name to export the Boolean network.
If the file extension is missing, then .txt is added. :param sep: The separator between formulas (default BOONSEP constant) :param assign: the operator defining the formula for a variable, e.g., a = f(…) → assign is ‘=’ (Default: ‘,’). :param ops: A dictionary stipulating how the operators And, Or, Not are syntactically written (Default: BOOLNET). :type filename: Str :type sep: str :type assign: str :type ops: dict :return: self :rtype: BooN
- property variables: set
Return the set of variables. :return: variables :rtype: set[Symbol]
- boon.asynchronous(variables: list | set) frozenset [source]
Asynchronous or sequential mode. One variable is updated per transition.
- Parameters:
variables (List or set) – List of variables.
- Returns:
of sets: {{x1},…,{xi},…,{xn}} representing the asynchronous mode.
- Return type:
frozenset[frozenset[Symbol]]
- boon.core2actions(core: frozenset) list [source]
Convert the core to a list of actions where an action is a list of (variable, Boolean). The actions are sorted by length, meaning that the more parsimonious actions are at first.
- Parameters:
core (Frozenset of literals.) – The core.
- Returns:
A list of combined actions where an action is defined as:[(variable, bool) …]
- Return type:
List[list[tuple]]
- boon.hypercube_layout(arg: int | nx.Digraph) dict [source]
Compute the hypercube layout of a graph.
- Parameters:
arg (Int or networkx Digraph) – The dimension of the hypercube or the network to which the layout is applied.
- Returns:
a dictionary {int:position} where int is the integer code of the hypercube labels.
- Return type:
Dict
- boon.int2state(int_state: int, variables: list | set) dict [source]
Convert an integer state to a dictionary state.
- Parameters:
int_state (Int) – The state coded into integer.
variables (list or set) – List of variables.
- Returns:
a dictionary representing the state {variable: boolean state…}.
- Return type:
Dict
- boon.is_controlled(formula) bool [source]
Check whether a formula is controlled.
- Parameters:
formula (Sympy formula.) – The input formula.
- Returns:
True if the formula is controlled otherwise False
- Return type:
bool
- boon.state2int(state: dict | tuple, variables: set | list | None = None) int [source]
Convert a set of states to an integer the binary profile of which corresponds to the state of the variables.
- Parameters:
state – State of the variables.
variables – List of variables.
If the list is empty, then the encoding order corresponds to the variable occur. (Defaults []) :type state: dict or tuple :type variables: list or set :return: an integer such that its binary profile represents the state. :rtype: Int
- boon.synchronous(variables: list | set) frozenset [source]
synchronous or parallel mode. All the variables are updated jointly per transition.
- Parameters:
variables (list or set) – list of variables.
- Returns:
of sets: {{x1,…,xi,…,xn}} representing the synchronous mode.
- Return type:
frozenset[frozenset[Symbol]]
Logic Module
This module includes functions on propositional formula.
- boon.logic.clause2literals(clause) set [source]
Convert a clause or a cube into of a sequence of literals.
- Parameters:
clause (Sympy formula) – The clause or cube.
- Returns:
set of literals.
- Return type:
Set
- boon.logic.cnf2clauses(cnf)[source]
Decomposition of a CNF into a sequence of clauses.
- Parameters:
cnf (sympy formula) – CNF formula
- Returns:
sequence of clauses.
- Return type:
Tuple[formula]
- boon.logic.errmsg(msg: str, arg='', kind: str = 'ERROR') None [source]
Display an error message and exit in case of error (keyword ERROR).
- Parameters:
msg – The error message.
arg – The argument of the error message (Default: “” no args).
kind – Type of error (Default: ERROR).
Only the “ERROR” option will exit the application. :type msg: str :type arg: str :type kind: str :return: None
- boon.logic.firstsymbol(formula)[source]
Extract the first symbol from the symbols of a dnf.
- Parameters:
formula (Sympy formula) – The input dnf.
- Returns:
the first symbol.
- boon.logic.newvar(initialize: int | None = None)[source]
Create a new sympy symbol of the form <prefix><number>. The prefix is given by TSEITIN constant.
- Parameters:
initialize (int|None) – Initialize the counter if the value is an integer or let the counter increment by 1 if it is set to None (Default value = None)
- Returns:
a Simpy symbol.
- Return type:
Symbol
- boon.logic.prettyform(formula, style: dict = {'type': 'infix', And: '∧', Equivalent: '⇔', False: 'false', Implies: '⇒', Not: '¬', Or: '∨', True: 'true', Xor: '⊻'}, depth=0)[source]
Return a string of a formula in nice form.
- Parameters:
formula (sympy formula) – The input formula.
style (dict) – The style of the logical operators (Default: LOGICAL)
depth (int) – the current depth of the formula for setting parentheses (Default: 0)
- boon.logic.prime_implicants(formula, kept: ~collections.abc.Callable = <function <lambda>>, trace: bool = False, solver: type = <class 'pulp.apis.coin_api.PULP_CBC_CMD'>) frozenset [source]
Compute all the prime implicants of a propositional formula where the literals are filtered by kept function. :param formula: The input formula. The formula does not need to be in CNF. :param kept: Predicate selecting the literals that are kept in the solutions (Default: function discarding the Tseitin working variables) :param trace: a Boolean flag determining whether the trace showing the resolution is activated (Default: False). :param solver: The solver to use (Default: Pulp solver). :type formula: Sympy formula :type kept: function :type trace: bool :type solver: solver function :return: all the prime implicants in the form of a set of sets where each subset represents one prime implicant filtered by kept. :rtype: Frozenset
- boon.logic.supercnf(formula, trace: bool = False)[source]
Convert the formula to CNF. The method is well adapted to large formula.
- Parameters:
formula (sympy formula) – The formula to convert.
trace (bool) – Boolean flag if True trace the computational steps (Default value = False)
- Returns:
CNF formula
- Return type:
sympy formula
- boon.logic.sympy2z3(formula)[source]
Convert a sympy formula to z3 formula.
- Parameters:
formula (Sympy formula) – The formula to convert.
- Returns:
the equivalent z3 formula.
- Return type:
Z3 formula
Boonify Module
Graphical interface module.
- class boonify.Boonify[source]
Main Class of the GUI
- class boonify.Threader(app=<function Threader.<lambda>>)[source]
Class executing a thread to run an application.