BoolSi

BoolSi is a command line tool for distributed simulations and analysis of synchronous Boolean networks. It uses MPI to parallelize across multiple compute nodes and/or cores.

<img src="./examples/output1_glider/simulations_SVG/simulation1.svg"/>

BoolSi can simulate a Boolean network from a range of initial states, identify and analyze network attractors, and find conditions that lead to specific states of the network. It also allows user to fix the state of any network node for the length of entire simulation (e.g. modeling gene knockout in regulatory networks), or perturb the state of the node at any time step (e.g. modeling sensory input in robotics).

• Installation
  • Prerequisites
  • PIP
  • Install from source
• MPI usage
• Quickstart
  • Example 1. Simulate network from example1.yaml for 5 steps
  • Example 2. Find and analyze attractors of a network
  • Example 3. Find simulations that reach specific states of a network
• Advanced usage
  • Fixed nodes
  • Perturbations
• Command line reference
• Input file reference
• Output
  • Graphical
  • CSV
• Questions and feedback
• Citations
• License

Installation

Prerequisites

BoolSi requires:

• Python 3.4 or higher

To use BoolSi with MPI you must also install:

• MPI Implementation (OpenMPI, MPICH)
• mpi4py Python library (https://mpi4py.readthedocs.io/)

For MPI Implementation installation instructions, please refer to vendor documentation:

• OpenMPI (https://www.open-mpi.org)
• MPICH (https://www.mpich.org)

We also expect BoolSi to work with other MPI Implementations, although they have not been tested.

To install mpi4py:

$ pip install mpi4py

All other Python package dependencies will be installed automatically when installing BoolSi.

PIP

$ pip install boolsi

Install from source

$ git clone https://github.com/boolsi/boolsi.git
$ cd boolsi
$ pip install .

MPI usage

To run BoolSi using MPI:

$ mpiexec -np [NUMBER OF PROCESSES] boolsi ...

Note that forceful termination in MPI (Abort) does not guarantee graceful shutdown of an application. As a consequence, aborting MPI run on Windows or in attract mode without the flag -i may leave orphaned files in the database directory (defaults to "<current directory>/tmp_db").

Quickstart

BoolSi provides 3 terminal commands to simulate Boolean networks:

• simulate to simulate for a number of time steps
• attract to find attractors (and analyze them for node correlations)
• target to find conditions leading to specific states of the network

Each command supports running simulations from multiple initial states at once, limiting the simulation time, and overriding the simulation process (see Advanced usage for the latter). All flags and arguments for the commands are covered in Command line reference.

Commands produce different types of output. simulate produces simulations — trajectories (sequences of network states) that start from the specified initial states of a network. attract produces attractors — repeating subsequences (of network states) in the trajectories of a network. target produces simulations, but only those that reach the specified target states of a network.

Boolean network to simulate needs to be described in a YAML file of the form (example1.yaml):

nodes:
    - A
    - B
    - C

update rules:
    A: not B
    B: A and C
    C: not A or B
    
initial state:
    A: 0
    B: 1
    C: any

Input file reference provides a detailed description of the input file syntax.

Let's run through some basic examples.

Example 1. Simulate network from example1.yaml for 5 steps

From the command line, run:

$ boolsi simulate examples/example1.yaml -t 5

Because the input file example1.yaml specifies multiple initial states (by using keyword any for node C), BoolSi will run separate simulation for each of them (A: 0, B: 1, C: 0 and A: 0, B: 1, C: 1):

18-Aug-2019 20:17:16 Hi! All BoolSi output (including this log) will appear in "/Users/user/boolsi/output_20190818T201716.666/".
18-Aug-2019 20:17:16 Run parameters: "simulate examples/example1.yaml -t 5".
18-Aug-2019 20:17:16 Initializing temporary storage in "/Users/user/boolsi/tmp_db/".
18-Aug-2019 20:17:16 Read Boolean network of 3 nodes.
18-Aug-2019 20:17:16 Single process will be used to perform 2 simulations...
...

The above also tells you where to look for the simulations after the run is finished (output_20190818T201716.666/):

<img src="./examples/output2_example1/simulation1.pdf.svg"/> <img src="./examples/output2_example1/simulation2.pdf.svg"/>

By default the results are printed in PDF, but other formats are available, including machine-readable CSV (see Output reference).

Example 2. Find and analyze attractors of a network

The input file example1.yaml specifies 2 initial states of the network to simulate from. If we want to find all attractors of the network, we need to simulate it from all possible initial states. For this, we create the input file example2.yaml, where the initial state of every node is set to any:

nodes:
    - A
    - B
    - C

update rules:
    A: not B
    B: A and C
    C: not A or B
    
initial state:
    A: any
    B: any
    C: any

Running the command:

$ boolsi attract examples/example2.yaml

will find all attractors and calculate correlations between the node states therein.

<img src="./examples/output3_example2/attractor1.pdf.svg"/> <img src="./examples/output3_example2/attractor2.pdf.svg" align="top"/> <img src="./examples/output3_example2/node_correlations.pdf.svg" align="top"/>

Example 3. Find simulations that reach specific states of a network

If we want to find conditions that lead to the states where e.g. A is 0 and B is 1, we first need to specify them as target states. For this, we create input file example3.yaml with added section target state. We also set the initial state of A to 1 in order to omit the trivial results, when the network starts in a target state.

nodes:
    - A
    - B
    - C

update rules:
    A: not B
    B: A and C
    C: not A or B
    
initial state:
    A: 1
    B: any
    C: any
   
target state:
    A: 0
    B: 1
    C: any

Running the command:

$ boolsi target examples/example3.yaml

will find the simulations reaching either A: 0, B: 1, C: 0 or A: 0, B: 1, C: 1.

<img src="./examples/output4_example3/simulation1.pdf.svg"/>

Advanced usage

BoolSi allows overriding the simulation process, which can be used to model external influence on the network. User can fix the state of any node for the entire simulation (e.g. modeling gene knockout in regulatory networks), or perturb it at any individual time step (e.g. modeling sensory input in robotics).

Fixed nodes

To permanently fix the state of a node, specify it under the fixed nodes section of the input file. For example, these lines set the state of node A to 0 and B to 1 for the entire simulation:

fixed nodes:
    A: 0
    B: 1

Adding the above to example1.yaml will make the simulations look like:

<img src="./examples/output5_example1_fixed_nodes/simulation1.pdf.svg"/> <img src="./examples/output5_example1_fixed_nodes/simulation2.pdf.svg"/>

When running simulate or target, it is also possible to use 0?, 1?, any, any? values.

    C: 0?

0? (1?) doubles the number of produced simulations by fixing the state of node C to 0(1), as well as simulating with unfixed C.

    C: any

any doubles the number of simulations by fixing the state of C separately to 0 and to 1.

    C: any?

any? triples the number of simulations by fixing the state of C separately to 0 and 1, as well as simulating with unfixed C.

Perturbations

To force a node into a particular state at an individual time step, use perturbations section. For example, to set the state of node A to 0 at time step 4 and to 1 at time step 5, and to set the state of node B to 1 at time steps 1, 2, 3, 5:

perturbations:
    A: 
        0: 4
        1: 5
    B:
        1: 1-3, 5

<img src="./examples/output6_example1_perturbations/simulation1.pdf.svg"/> <img src="./examples/output6_example1_perturbations/simulation2.pdf.svg"/>

Similarly to fixed nodes, it is possible to use 0?, 1?,any, any? values when running simulate or target. For example, the following lines increase the number of produced simulations by a factor of 2⁴ = 16 because the state to force C into (0 or 1) is considered independently at each time step.

perturbations:
    C: 
        any: 2, 3, 5, 7

When running attract or target, BoolSi starts looking for attractors or target states only after all perturbations have occurred.

Command line reference

To run BoolSi, open the terminal and type:

boolsi COMMAND [ARGS] [OPTIONS]

You can stop BoolSi at any point by pressing Ctrl+C.

Commands:

simulate Perform simulations.

attract Find (and analyze) attractors.

target Find simulations that reach target states.

Common arguments:

input_file [required] Path to YAML file describing the Boolean network.

Common options

-h, --help Prints help for the current command.

-o, `--output-dire