CABEAN

CABEAN: A Software Tool for the Control of Asynchronous Boolean Networks

Description

CABEAN is a software tool for the control of asynchronous Boolean networks, which are often used to model gene regulatory networks.

Features

CABEAN provides the following methods for the efficient control of asynchronous Boolean networks:

Download

CABEAN is freely available. The newest version of CABEAN is 1.0.0, updated on April 17, 2020. You can download the files here, including executable binaries for Windows, Mac or Linux, a detailed user guide and examples.

Quickstart Guide

In this quick guide, we introduce the basic usages of CABEAN, including the syntax of the model file and how to compute the minimal control with and without practical constraints. For detailed introduction of CABEAN, please download the user guide.

How to define a Boolean network?

Nodes Functions Indices of attractors Attractors
x1     f1= x2 A1 001100
x2    f2= x1A2 001111
x3    f3= (~x2) ∨ x4 A3 110000
x4    f4= x3A4 110010
x5     f5= (x1 ∨ x6) ∧ x5 A5 111100
x6    f6=x4 ∧ x5 A6 111111

Table 1. The Boolean functions and the attractors of the example.

The first two columns of Table 1 describe a Boolean network with six nodes, including x1, x2, x3, x4, x5, and x6. Each node is assigned with a Boolean function. The model file of the network is under ISPL format (Interpreted Systems Programming Language) as shown below. It contains two sections: section 'Agent M' and section 'InitStates'. Section 'Agent M' defines the Boolean variables and the Boolean functions of the network; section 'InitStates' specifies the initial state. Section 'Agent M' includes four parts: 'Vars', 'Actions', 'Protocol', and 'Evolution'. The 'Vars' part defines the Boolean variables and the order of the variables is consistent with the order of the nodes in each state in the output. The 'Evolution' part specifies the Boolean functions for each variable. The functions are defined using parenthesis and three logical operations, including logical and '&', logical or '|'', and logical not '~'. Note that the logical not operation is required to be surrounded by a pair of parenthesis, e.g., (~x2). The 'Actions' and 'Protocol' parts are defined as '{none}'.
Agent M
  Vars:    
    x1: boolean;
    x2: boolean;    
    x3: boolean;
    x4: boolean;
    x5: boolean;
    x6: boolean;
  end Vars
  Actions = {none};
  Protocol:
    Other: {none};
  end Protocol
  Evolution:
    x1=true  if  x2=true;
    x1=false if  x2=false;    
    x2=true  if  x1=true;
    x2=false if  x1=false;
    x3=true  if  (~x2)|x4=true;
    x3=false if  (~x2)|x4=false;
    x4=true  if  x3=true;
    x4=false if  x3=false;
    x5=true  if  (x1|x6)&x5=true;
    x5=false if  (x1|x6)&x5=false;
    x6=true  if x4&x5=true;
    x6=false if x4&x5=false;
  end Evolution
end Agent

InitStates
    M.x1=true or M.x1=false;
end InitStates

The model file of the example. (Download: example.ispl)

As shown in Table 1, this network has six attractors. Users can use the provided functions to compute the minimal control for one pair of source and target attractors or for all combinations of source and target attractors.

How to compute the control for one pair of source and target attractors?

The minimal control from the source attractor to the target attractor can be computed using the following command line:

./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control <control method> -sin <indice of the source> -tin <indice of the target> <model file>

In the command line, options '-steadystates -asynbn -newtarjan -newpred' are mandatory; '-compositional 2' implies that the strong basin and weak basins of attractors are computed using the decomposition-based fixpoint computation methods [BCB18, TCBB19]; '-control <control method>' indicates the control method (OI, OT, OP, ASI, AST or ASP) to be applied; '-sin <indice of the source> -tin <indice of the target>' indicates the indices of the source and target attractors; '<model file>' is the name of the model file and it is always placed at the end of the command line. CABEAN first identifies all the exact attractors of the network and then compute the minimal control for the specified source and target attractors. For instance, to compute the minimal OT control from A6 to A1, we use the folloing command line:

./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control OT -sin 6 -tin 1 example.ispl
The results are shown below. We can see that CABEAN identified six attractors (in lexicographic order) and eight minimal OT control sets. For this case, the minimal OT control requires at least two perturbations.
Command line: ./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control OT 
-sin 6 -tin 1 example.ispl
======================== find attractor #1 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-0-0-  1

======================== find attractor #2 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-1-1-  1

======================== find attractor #3 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-0-0-  1

======================== find attractor #4 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-1-0-  1

======================== find attractor #5 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-0-0-  1

======================== find attractor #6 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-1-1-  1

number of attractors = 6
time for attractor detection=0.001 seconds

====== ONE-STEP TEMPORARY SOURCE-TARGET CONTROL (DECOMP) ======

source - 6 target - 1

PATH 1 - #perturbations: 2
  Control set: x2=0 x6=0 

PATH 2 - #perturbations: 2
  Control set: x2=0 x5=0 

PATH 3 - #perturbations: 2
  Control set: x2=0 x4=0 

PATH 4 - #perturbations: 2
  Control set: x2=0 x3=0 

PATH 5 - #perturbations: 2
  Control set: x1=0 x6=0 

PATH 6 - #perturbations: 2
  Control set: x1=0 x5=0 

PATH 7 - #perturbations: 2
  Control set: x1=0 x4=0 

PATH 8 - #perturbations: 2
  Control set: x1=0 x3=0 
execution time for control = 0.003 seconds

Results of the minimal OT control from A6 to A1. (Download: example-OT-6to1.txt)

How to compute the control for one pair of source and target attractors with constraints on perturbations?

CABEAN allows users to specify undesired perturbations and compute the minimal control excluding those perturbations. In the current version, user can define three types of perturbaions: Suppose node x5 can not be flipped from 1 to 0 and nodes x4 and x6 can not be perturbed in any direction. The specification file is given below.
R0: 
R1: x5
R: x4, x6
File for the specification of undesired perturbations. (Download: rmPert.txt)

To compute the minimal OT control from A6 to A1 without undesired perturbations, we add option '-rmPert <file name>' to the command line as follows:
./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control OT -sin 6 -tin 1 -rmPert rmPert.txt example.ispl
The output of CABEAN is given below. We can see that the minimal OT control still requires at least two perturbations and there are two solutions without undesired perturbations.
Command line: ./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control OT 
-sin 6 -tin 1 -rmPert rmPert.txt example.ispl
======================== find attractor #1 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-0-0-  1

======================== find attractor #2 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-1-1-  1

======================== find attractor #3 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-0-0-  1

======================== find attractor #4 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-1-0-  1

======================== find attractor #5 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-0-0-  1

======================== find attractor #6 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-1-1-  1

number of attractors = 6
time for attractor detection=0.002 seconds

====== ONE-STEP TEMPORARY SOURCE-TARGET CONTROL (DECOMP) ======

source - 6 target - 1

PATH 1 - #perturbations: 2
  Control set: x2=0 x3=0 

PATH 2 - #perturbations: 2
  Control set: x1=0 x3=0 
execution time for control = 0.001 seconds

Results of the minimal OT control from A6 to A1 with constraints on perturbations. (Download: example-OT-6to1-rmPert.txt)

How to compute the control for all pairs of source and target attractors?

CABEAN allows us to compute the minimal control for each possible combination of source and target attractors by replacing '-sin <indice of the source> -tin <indice of the target>' with '-allpairs' in the command line. For the example given in Table 1, the minimal OT control for all pairs of source and target attractors can be computed using the following command line:
./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control OT -allpairs example.ispl
The results can be downloaded here (example-OT-allpairs.txt).

How to compute attractor-based sequential control with constraints on the intermediate attractors?

For attractor-based sequential control (ASI, AST and ASP), undesired attractors, such as attractors that correspond to diseased cells, can be avoided from being adopted as intermediate attractors. Suppose attractors A2 and A5 are the undesired ones, we can define them in the file 'rmID.txt' as follows (the indices are separated by comma):
2,5
File for the speicification of undesired attractors. (Download: rmID.txt)
Taking ASI control as an example, we first show its results without any predefined constraints below. Note that ASI control use the minimal number of perturations required by the minimal OI control as the threshold and computes all the sequential paths within the threshold. We can see that besides the one-step control path, there are two sequential control paths from A6 to A1, where A2 and At act as the intermediate attractors, respectively.
Command line: ./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control ASI 
-sin 6 -tin 1 example.ispl
======================== find attractor #1 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-0-0-  1

======================== find attractor #2 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-1-1-  1

======================== find attractor #3 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-0-0-  1

======================== find attractor #4 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-1-0-  1

======================== find attractor #5 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-0-0-  1

======================== find attractor #6 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-1-1-  1

number of attractors = 6
time for attractor detection=0.002 seconds

========= ATTRACTOR-BASED SEQUENTIAL INSTANTANEOUS SOURCE-TARGET CONTROL (DECOMP) =========

source - 6 target - 1

PATH 1 - #perturbations: 3
Sequence of the attractors: 6 -> 1
  STEP 1
    Control set 1: x1=0 x2=0 x5=0 

PATH 2 - #perturbations: 3
Sequence of the attractors: 6 -> 2 -> 1
  STEP 1
    Control set 1: x1=0 x2=0 
  STEP 2
    Control set 1: x5=0 

PATH 3 - #perturbations: 3
Sequence of the attractors: 6 -> 5 -> 1
  STEP 1
    Control set 1: x5=0 
  STEP 2
    Control set 1: x1=0 x2=0 
execution time of control=0.004 seconds

Results of ASI control from A6 to A1. (Download: example-ASI-6to1.txt)
Now, we add constraints on the intermediate attractors by inserting '-rmID rmID.txt' to the command line and the output is given below. The two sequential paths passing though the undesired attractors are eliminated from the results.

Command line: ./cabean -steadystates -asynbn -newtarjan -newpred -compositional 2 -control ASI 
-sin 6 -tin 1 -rmID rmID.txt example.ispl
======================== find attractor #1 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-0-0-  1

======================== find attractor #2 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
0-0-1-1-1-1-  1

======================== find attractor #3 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-0-0-  1

======================== find attractor #4 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-0-0-1-0-  1

======================== find attractor #5 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-0-0-  1

======================== find attractor #6 : 1 states ========================
: 7 nodes 1 leaves 1 minterms
1-1-1-1-1-1-  1

number of attractors = 6
time for attractor detection=0.001 seconds

========= ATTRACTOR-BASED SEQUENTIAL INSTANTANEOUS SOURCE-TARGET CONTROL (DECOMP) =========

IDs of undesired attractors
2 5 
source - 6 target - 1

PATH 1 - #perturbations: 3
Sequence of the attractors: 6 -> 1
  STEP 1
    Control set 1: x1=0 x2=0 x5=0 
execution time of control=0.002 seconds

Results of ASI control from A6 to A1 with constraints on the intermediate attractors. (Download: example-ASI-6to1-rmID.txt)

Requirements

1. Platform: x86 compatible 32 bit or 64 bit processor;

2. Operating system: Windows, Linux and Mac OSX (10.4 and above);

3. Required compilers: flex 2.6.4 or higher, GNU bison 3.0.4 or higher, GNU g++ 4.0.1 or higher, and Windows subsystem for Linux (Windows platform only).

References