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 run boonify.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) → None[source]

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).

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.

copy() → BooN[source]

Perform a deep copy of the Boolean network.

delete(variable) → None[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.

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 for 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) → None[source]

Convert formula(s) of the Boolean network to DNF.

Parameters:

  • variable (Symbol) – 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.

  • simplify (bool) – Boolean flag determining whether the formula should be simplified (Default: True).

  • force (bool) – Boolean flag forcing the complete simplification (Default: True).

draw_IG(IG: DiGraph | None = None, modular: bool = False, **kwargs)[source]

Draw the interaction graph.

Parameters:

  • IG (networkx DiGraph) – the interaction graph or None. If None, the interaction graph is generated from BooN (Default: None).

  • modular (bool) – Boolean indicating whether the modular structure of interactions is displayed if True (Default: False)

  • kwargs (dict) – additional keyword arguments to pass to the interaction graph drawing

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 (networkx DiGraph) – input datamodel graph of the BooN or None (Default: None). if it is None the asynchronous datamodel computed from the BooN.

  • mode (function) – function characterizing the mode of the datamodel (Default: asynchronous)

  • color (list) – list of colors for highlighting the equlibria (Default: COLOR)

  • kwargs (dict) – extra parameters of nx.draw_networkx.

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 variable (max. ~10).

Parameters:

  • model (networkx DiGraph) – data model from which the equilibria are calculated. If the datamodel is None, then the datamodel will be calculated from BooN. (Default: None)

  • mode (function) – updating mode function, used if the datamodel is None (Default: asynchronous).

Returns:

Equilibria structure as a list of lists where each sublist is an attractor.

Return type:

list[list]

from_ig(IG: DiGraph)[source]

Define the descriptor of a BooN from an interaction graph.

Parameters:

IG – interaction graph.

from_sbmlfile(filename: str) → None[source]

Import the Boolean network from a sbml file.

Parameters:

filename (str) – the file name to import the Boolean network. If the extension is missing then .sbml is added.

from_textfile(filename: str, sep: str = '\n', assign: str = ',', ops: dict = {'type': 'normal form', And: '&', False: '0', Not: '!', Or: '|', True: '1'}) → None[source]

Import the Boolean network from a text file. The syntax depend on the ops’ descriptor. The formulas must be in normal form containing OR, AND, NOT operators only. The nodes are circularly mapped.

Parameters:

  • filename (str) – the file name to import the Boolean network. If the file extension is missing then .txt is added.

  • sep (str) – the separator between definitions (default BOONSEP constant)

  • assign (str) – the operator defining the formula for a variable, e.g. a = f(…) -> assign is ‘=’ (Default: ‘,’).

  • ops (dict) – a dictionary stipulating how the operators And, Or, Not are syntactically written (Default: BOOLNET).

property interaction_graph: DiGraph

Build the interaction graph.

Returns:

the interaction graph.

Return type:

networkx DiGraph

load(filename: str) → None[source]

Load the Boolean Network from file. If the extension is missing then .boon is added.

Parameters:

filename (str) – the name of the file to load the network.

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.

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) → None[source]

Rename a variable.

Parameters:

  • source (Symbol) – the variable to rename.

  • target (Symbol) – the variable renaming the source.

save(filename: str = 'BooN05-sept.-24-14.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)

stability_constraints()[source]

Define the stability constraints for a BooN.

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 = '=')[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'}) → None[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 (str) – the file name to export the Boolean network. If the file extension is missing then .txt is added.

  • sep (str) – the separator between formulas (default BOONSEP constant)

  • assign (str) – the operator defining the formula for a variable, e.g. a = f(…) -> assign is ‘=’ (Default: ‘,’).

  • ops (dict) – a dictionary stipulating how the operators And, Or, Not are syntactically written (Default: BOOLNET).

property variables: set

Return the set of variables.

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:

set 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 (dict or tuple) – state of the variables.

  • variables (list or set) – list of variables. If the list is empty then the encoding order corresponds to the variable occur. (Defaults [])

Returns:

an integer such that its binary profile represents the state.

Return type:

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:

set 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 (str) – the error message.

  • arg (str) – the argument of the error message (Default: “” no args).

  • kind (str) – type of error (Default: ERROR). only the “ERROR” option will exit the application.

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 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.

Parameters:

  • formula (sympy formula) – the input formula. The formula does not need to be in CNF.

  • kept (function) – predicate selecting the literals that are kept in the solutions (Default: function discarding the Tseitin working variables)

  • trace (bool) – Boolean flag determining whether the trace showing the resolution is activated (Default: False).

  • solver (solver function) – the solver to use (Default: Pulp solver).

Returns:

all the prime implicants in the form of a set of sets where each subset represent one prime implicant filtered by kept.

Return type:

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

boon.logic.tseitin(formula)[source]

Characterize the Tseitin form of a formula. The additional variables are prefixed by TEITSIN constant

Parameters:

formula (sympy formula) – the formula.

Returns:

a pair: Tseitin variable, Tseitin CNF.

Return type:

tuple

boon.logic.tseitin_cnf(formula)[source]

Convert a formula to CNF using Tseitin method.

Parameters:

formula (sympy formula) – the formula to be converted.

Returns:

CNF formula.

Return type:

sympy formula

Boonify Module

Graphical interface module.

class boonify.Boonify[source]

Main Class of the GUI

add_history()[source]

Add current BooN to the history.

closeEvent(event)[source]

Close window

controllability()[source]

Controllability View

design()[source]

interaction graph design callback.

exportation()[source]

Export file dialog.

help()[source]

Help View

history_raz()[source]

Clear the history.

importation()[source]

Import file dialog.

model()[source]

Model View

open()[source]

Open the file dialog.

quit()[source]

Quit application.

redo()[source]

Redo operation.

refresh()[source]

Refresh the opened widgets.

resizeEvent(event, **kwargs)[source]

Modify graph parameters so that node and edge widths are invariant to window resizing.

save()[source]

Save file dialog.

saveas()[source]

Save as the file as dialog.

setup_design()[source]

Set up of the editable graph.

show_history()[source]

Display the history.

stablestates()[source]

Stable States View

undo()[source]

Undo operation.

view()[source]

BooN View

class boonify.Controllability(parent=None)[source]

Controllability class

actupon()[source]

Apply the selection actions on the BooN.

controllability()[source]

Compute the control actions based on the destiny and the observers.

destiny_to_observers(label: str)[source]

Modify the observer w.r.t. the destiny change.

initialize_controllability()[source]

Initialize the controllability widget.

observers_to_destiny(chkitem)[source]

Modify the destiny w.r.t. the observer change

select_action(arg)[source]

Keep the selection solution

class boonify.Help(parent=None)[source]

Help Class used for showing help.

class boonify.Model(parent=None)[source]

Class to handle model of dynamics.

cb_network_layout()[source]

Determine the layout of the network model from the combo box.

modeling()[source]

Compute the model of dynamics.

rb_mode()[source]

Mode selection from radio button box.

class boonify.StableStates(parent=None)[source]

Class to handle stable states computation.

cb_styling()[source]

Select style from combo box selection

stablestates()[source]

Compute stable states and arrange the view.

class boonify.Threader(app=<function Threader.<lambda>>)[source]

Class executing a thread to run an application.

apply(app)[source]

Fix the application running in the thread.

quit()[source]

terminate the thread

run()[source]

run the application

class boonify.View(parent=None)[source]

View Class used for showing the BooN formula in a table.

cb_styling()[source]

Style from combo box selection

change_formula()[source]

Update the BooN from a formula change.

convertdnf()[source]

Convert the BooN into DNF.

initialize_view()[source]

Fill the table.

Indices and tables