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 = {})

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

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:

BooN

control(frozenfalse: set | list | frozenset, frozentrue: set | list | frozenset) → None

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:

BooN

copy() → BooN

Perform a deep copy of the Boolean network.

delete(variable) → BooN

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:

BooN

static destify(query, trace: bool = False, solver=<class 'pulp.apis.coin_api.PULP_CBC_CMD'>)

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

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

Returns:

modified BooN

Return type:

BooN

draw_IG(IG: DiGraph | None = None, modular: bool = False, **kwargs) → DiGraph

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

Returns:

interaction graph

Return type:

Networkx DiGraph

draw_model(model: ~networkx.classes.digraph.DiGraph | None = None, mode: ~collections.abc.Callable = <function asynchronous>, color: list[str] = ['tomato', 'gold', 'yellowgreen', 'plum', 'mediumaquamarine', 'darkorange', 'darkkhaki', 'forestgreen', 'salmon', 'lightcoral', 'cornflowerblue', 'orange', 'paleviolet', 'coral', 'dodgerblue', 'yellowgreen', 'orangered', 'pink', 'blueviolet', 'crimson'], **kwargs) → None

Draw the graph representing the model of dynamics.

Parameters:

• model (Networkx DiGraph) – Input graph model of the BooN or None (Default: None). If it is None, the asynchronous model computed from the BooN.

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

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

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

Returns:

None

Return type:

None

equilibria(model: ~networkx.classes.digraph.DiGraph | None, mode: ~collections.abc.Callable = <function asynchronous>) → list[list]

Calculate equilibria for the network based on model of 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 (Networkx DiGraph) – Data model from which the equilibria are calculated.

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

Returns:

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

Return type:

List[list]

classmethod from_ig(IG: nx.DiGraph) → Boon

Define the descriptor of a BooN from an interaction graph. The method is a class method.

Parameters:

IG – Interaction graph.

Returns:

BooN

Return type:

BooN

classmethod from_sbmlfile(filename: str) → BooN

Import the Boolean network from a sbml file. The method is a class method.

Parameters:

filename (str) – the name of the file, if the extension is missing then .sbml is added.

Returns:

BooN

Return type:

BooN

classmethod from_textfile(filename: str, sep: str = '\n', assign: str = ',', ops: dict = {'type': 'normal form', And: '&', False: '0', Not: '!', Or: '|', True: '1'}, skipline: str = '(targets\\s*,\\s*factors)|(#.*)') → BooN

Import the Boolean network from a text file, the syntax of which depends on the ops’ descriptor. The formulas must be in normal form containing OR, AND, NOT operators only. The nodes are circularly mapped. The default format is the Bool Net format (see ops and assign defaults). The method is a class method.

Parameters:

• filename (Str) – The file name to import the Boolean network. If the file extension is missing, then .bnet 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).

• skipline (str (regexp)) – Regular expression describing which lines must be skipped and not analyzed.

Returns:

BooN

Return type:

BooN

property interaction_graph: DiGraph

Build the interaction graph.

Returns:

The interaction graph.

Return type:

Networkx DiGraph

classmethod load(filename: str) → BooN

Load the Boolean Network from a file. If the extension is missing, then .boon is added. The method is a class method

Parameters:

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

Returns:

self

Return type:

BooN

model(mode: ~collections.abc.Callable = <function asynchronous>, self_loop: bool = False) → DiGraph

Compute the dynamical model of the BooN with respect to a mode.

Parameters:

• self_loop (Bool) – Determines whether the boon loops are included in the model (Default: False).

• mode (function) – Determines the mode policy applied to the model (Default: asynchronous).

Returns:

a Digraph representing the complete state-based dynamics.

Return type:

Networkx Digraph

necessary(query, trace: bool = False)

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)

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

classmethod random(n: int, p_link: float, p_pos: float = 0.5, topology: str = 'Erdos-Reny', min_clauses: int = 1, max_clauses: int = 5, prefix: str = 'x') → BooN

Generate a random BooN where the formulas are in DNF. The method is a class method.

Parameters:

• n (int) – The number of variables.

• p_link – probability related to interaction between variables, the use depends on the topology class.

• p_pos (float) – The probability of defining a variable as a positive term (default 0.5).

• topology (str) – the topology class of the interaction graph: ‘Erdos-Reny’, ‘Scale-Free’, ‘Small-World’ (default ‘Erdos-Reny’)

• min_clauses (int) – the minimum number of clauses required to define a formula (default 1).

• max_clauses (int) – the minimum number of clauses required to define a formula (default 5).

• prefix (str) – the prefix of the variable name, the variables are of the form <prefix><int> (default ‘x’).

Returns:

a random BooN

Return type:

BooN

rename(source: Symbol, target: Symbol) → BooN

Rename a variable.

Parameters:

• source (Symbol) – The variable to rename.

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

save(filename: str = 'BooN09-nov.-24-18.boon') → None

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

stability_constraints()

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 = '=') → str

Return a string representing the BooN. The output format can be parameterized (see style argument of BooN)

Parameters:

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

• assign (str) – the operator defining the assignment of a formula to a variable (e.g., a = f(…) → assign is ‘=’). (Default: ‘=’)

to_textfile(filename: str, sep: str = '\n', assign: str = ',', ops: dict = {'type': 'normal form', And: '&', False: '0', Not: '!', Or: '|', True: '1'}, header: str = '# BooN saved on 09-11-2024\ntargets, factors') → BooN

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.

• 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: ‘,’ Boolnet Format).

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

• header (str) – Header text inserted at the beginning of the saved file.

Returns:

self

Return type:

BooN

property variables: set

Return the set of variables. (property) :return: Variables :rtype: set[Symbol]

boon.asynchronous(variables: list | set) → frozenset

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

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

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

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

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

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.

Returns:

an integer such that its binary profile represents the state.

Return type:

Int

boon.synchronous(variables: list | set) → frozenset

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

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)

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

Display an error message and exit in case of error (kind = “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.

Returns:

None

Return type:

None

boon.logic.firstsymbol(formula)

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)

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)

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

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) – a 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 represents one prime implicant filtered by kept.

Return type:

Frozenset

boon.logic.supercnf(formula, trace: bool = False)

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)

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)

Characterize the Tseitin form of a formula. TEITSIN constant prefixes the additional variables.

Parameters:

formula (Sympy formula) – The formula.

Returns:

a pair: Tseitin variable, Tseitin CNF.

Return type:

Tuple

boon.logic.tseitin_cnf(formula)

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

Main Class of the GUI

add_history()

Add current BooN to the history.

closeEvent(event)

Close window

controllability()

Controllability View

design()

interaction graph design callback.

exportation()

Export file dialog.

help()

Help View

history_raz()

Clear the history.

importation()

Import file dialog.

model()

Model View

open()

Open the file dialog.

quit()

Quit application.

redo()

Redo operation.

refresh()

Refresh the opened widgets.

resizeEvent(event, **kwargs)

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

save()

Save file dialog.

saveas()

Save as the file as dialog.

setup_design()

Set up of the editable graph.

show_history()

Display the history. Used to debug the history management.

stablestates()

Stable States View

undo()

Undo operation.

view()

BooN View

class boonify.Controllability(parent=None)

Controllability class

actupon()

Apply the selection actions on the BooN.

controllability()

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

destiny_to_observers(label: str)

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

initialize_controllability()

Initialize the controllability widget.

observers_to_destiny(chkitem)

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

select_action(arg)

Keep the selection solution

class boonify.Help(parent=None)

Help Class used for showing help.

class boonify.Model(parent=None)

Class to handle model of dynamics.

cb_network_layout()

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

modeling()

Compute the model of dynamics.

rb_mode()

Mode selection from radio button box.

class boonify.StableStates(parent=None)

Class to handle stable states computation.

cb_styling()

Select style from combo box selection

stablestates()

Compute stable states and arrange the view.

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

Class executing a thread to run an application.

apply(app)

Fix the application running in the thread.

quit()

terminate the thread

run()

run the application

class boonify.View(parent=None)

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

cb_styling()

Style from combo box selection

change_formula()

Update the BooN from a formula change.

convertdnf()

Convert the BooN into DNF.

initialize_view()

Fill the table.

Indices and tables

• Index

• Module Index

• Search Page