CABEAN is a software tool for the control of asynchronous Boolean networks, which are often used to model gene regulatory networks.
The source-target control of asynchronous Boolean networks can be achieved either in one step, called one-step control, or in multiple steps, called sequential control. Taking difficulties in practical applications into consideration, we are particularly interested in the sequential control through other attractors, called attractor-based sequential control. Figure 1(a) and Figure 1(b) illustrate the one-step and attractor-based sequential control, respectively. Squares and rhombuses represent the source and target attractors. Circles represent the other attractors of the network. One-step control drives the network from the source directly to the target, while attractor-based sequential control employs other attractors as intermediate and identifies a sequence of perturbations. Based on the application time of control, we have instantaneous, temporary and permanent controls. Instantaneous control applies perturbations instantaneously; temporary control applies perturbations for sufficient time and then released; and permanent control applies the control for all the following time steps.
CABEAN is freely available. The newest version of CABEAN is 1.0.2, updated on July 14, 2020. You can download the files here, including executable binaries for Windows, Mac or Linux, a detailed user guide and examples. Starting from version 1.0.1, CABEAN supports model files under BoolNet format.
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).
In this quick guide, we use two examples to illustrate the basic usages of CABEAN, including the syntax of the model file and how to compute different controls with and without practical constraints. Specifically, Example 1 focuses on the introduction of different control methods and Example 2 shows how to encode practical constraints. For detailed introduction of CABEAN, please download the user guide.
Nodes | Functions | Indices of attractors | Attractors |
---|---|---|---|
x_{1} | f_{1}= x_{2} | A_{1} | 000 |
x_{2} | f_{2}= x_{1} | A_{2} | 110 |
x_{3} | f_{3}= x_{2} ∧ x_{3} | A_{3} | 111 |
The first two columns of Table 1 describe a Boolean network with three nodes,
including x_{1}, x_{2}, x_{3}.
Each node is assigned with a Boolean function.
CABEAN supports the BoolNet and ISPL (Interpreted Systems Programming Language) format.
We recommend the BioLQM toolkits for the conversion of other formats, such as SBML-qual, Petri net, GINsim, to BoolNet format.
BioLQM is available at http://colomoto.org/biolqm/.
BoolNet describes a Boolean network or probabilistic Boolean network in a standardized text file format.
Here we only explain the syntax for Boolean networks.
The model file of the example under BoolNet format is given below.
The first line is a header: 'targets, factors'.
The name and the Boolean function of each node are separated by a comma and given at each line.
The header implies the format: 'targets' is the name of the node and 'factors' represents the Boolean function of the node.
In the Boolean functions, the logical operators 'and', 'or' and 'not' are represented as '&', '|' and '!'.
Users can initialise the value of an input node to either '1' or '0'.
targets, factors x1, x2 x2, x1 x3, x2&x3
The model file under ISPL format is 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 '~'. The 'Actions' and 'Protocol' parts are defined as '{none}'. The ISPL format is preferable than BoolNet format. In the following sections, we use 'toy.ispl' as the name of the model file.
Agent M Vars: x1: boolean; x2: boolean; x3: 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&x3=true; x3=false if x2&x3=false; end Evolution end Agent InitStates M.x1=true or M.x1=false; end InitStates
CABEAN implements the decomposition-based attractor detection method [APBC18] that can identify all the exact attractors of the network. The attractors of the example can be computed using the following command:
Command line: ./cabean -compositional 2 toy.ispl ======================== find attractor #1 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 0-0-0- 1 ======================== find attractor #2 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-0- 1 ======================== find attractor #3 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-1- 1 number of attractors = 3 time for attractor detection=0.001 seconds
In the previous section, we showed how to use CABEAN for the identification of attractors. Below is a template command line for computing the control from the source attractor to the target attractor.
In the command line,
'-compositional 2' implies that the strong basin of an attractors is computed using the decomposition-based computation methods [BCB18, TCBB19];
'-control <control method>' indicates the control method (OI, OT, OP, ASI, AST or ASP);
'-sin <indice of the source> -tin <indice of the target>' indicates the indices of the source and target attractors;
'<model file>' is the path of the model file and it is always placed at the end of the command line.
In this way, the source and target correspond to one of the attractors of the network.
The attractor can be either a single-state attractor or a cyclic attractor.
If the source attractor is cyclic, CABEAN will identify the control to be applied to a state in the source attractor that requires the fewest number of perturbations.
Currently, CABEAN does not support the control from/to a set of attractors.
CABEAN first identifies all the exact attractors of the network and then compute the control for the specified source and target attractors.
For this example, let us assume A_{1} and A_{3} are the source and the target attractors, respectively.
Next we show how to compute OI, OT, OP, ASI, AST and ASP from A_{1} to A_{3} with CABEAN.
We use the following command line to compute the minimal OI control from A_{1} to A_{3} for Example 1.
The results are shown below. CABEAN identifies one minimal OI control {x1=1 x2=1 x3=1}. To compute the minimal OI contol, our method computes the strong basin of the target attractor and then finds the intermediate state in the strong basin that has the shortest Hamming distance to the source state. The nodes that have different values in the source state and the intermediate state are the driver nodes. Figure 2(a) shows that the strong basin of A_{3} contains only one state (111). Thus, the minimal OI control drives the network from (000) to (111) and the associate control set is {x1=1 x2=1 x3=1}.
Command line: ./cabean -compositional 2 -control OI -sin 1 -tin 3 toy.ispl ======================== find attractor #1 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 0-0-0- 1 ======================== find attractor #2 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-0- 1 ======================== find attractor #3 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-1- 1 number of attractors = 3 time for attractor detection=0.001 seconds ====== ONE-STEP INSTANTANEOUS SOURCE-TARGET CONTROL (DECOMP) ====== source - 1 target - 3 PATH 1 - #perturbations: 3 Control set: x1=1 x2=1 x3=1 execution time of control = 0 seconds
We use the following command line to compute the minimal OT control from A_{1} to A_{3} for Example 1.
The results are shown below. To compute the minimal OT contol, our method explores the weak basin of the target attractor starting from the state that has the shortest Hamming distance to the source state and verify if the corresponding control is a valid temporary control or not. If so, we are done and the control is the minimal OT control. Otherwise, we proceed to the next state that has the shortest Hamming distance to the source state and repeat the verification process. As shown in Figure 2(a), the weak basin of A_{3} consists of three states: (011), (101) and (111). States (011) and (101) have the shortest Hamming distance to A_{1}. For state (011), the corresponding control set is C_{1}={x2=1 x3=1}. The application control of C_{1} stirs the network from state (000) to (011) and reshapes the transition system from Figure 2(a) to Figure 2(b). During the control, the network will eventually and surely reach the target attractor A_{3}. Therefore, C_{1} is a minimal OT control. Similarly, we can prove that the control C_{2}={x1=1 x3=1} associated with the intermediate state (011) is also a minimal OT control. (Figure 2(c) shows the transition system under control C_{2}. )
Command line: ./cabean -compositional 2 -control OT -sin 1 -tin 3 toy.ispl ======================== find attractor #1 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 0-0-0- 1 ======================== find attractor #2 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-0- 1 ======================== find attractor #3 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-1- 1 number of attractors = 3 time for attractor detection=0 seconds ====== ONE-STEP TEMPORARY SOURCE-TARGET CONTROL (DECOMP) ====== source - 1 target - 3 PATH 1 - #perturbations: 2 Control set: x2=1 x3=1 PATH 2 - #perturbations: 2 Control set: x1=1 x3=1 execution time for control = 0.001 seconds
We use the following command line to compute the minimal OP control from A_{1} to A_{3} for Example 1. The results of the minimal OP control are the same with the minimal OT control. To avoid duplication, we omit the output of OP control here (toy-OP.txt).
We use the following command line to compute the minimal ASI control from A_{1} to A_{3} for Example 1.
Command line: ./cabean -compositional 2 -control ASI -sin 1 -tin 3 toy.ispl ======================== find attractor #1 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 0-0-0- 1 ======================== find attractor #2 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-0- 1 ======================== find attractor #3 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-1- 1 number of attractors = 3 time for attractor detection=0.001 seconds ========= ATTRACTOR-BASED SEQUENTIAL INSTANTANEOUS SOURCE-TARGET CONTROL (DECOMP) ========= source - 1 target - 3 PATH 1 - #perturbations: 3 Sequence of the attractors: 1 -> 3 STEP 1 Control set 1: x1=1 x2=1 x3=1 PATH 2 - #perturbations: 3 Sequence of the attractors: 1 -> 2 -> 3 STEP 1 Control set 1: x1=1 x2=1 STEP 2 Control set 1: x3=1 execution time of control=0 seconds
We use the following command to compute the minimal AST control from A_{1} to A_{3} for Example 1.
Command line: ./cabean -compositional 2 -control AST -sin 1 -tin 3 toy.ispl ======================== find attractor #1 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 0-0-0- 1 ======================== find attractor #2 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-0- 1 ======================== find attractor #3 : 1 states ======================== : 4 nodes 1 leaves 1 minterms 1-1-1- 1 number of attractors = 3 time for attractor detection=0 seconds ========= ATTRACTOR-BASED SEQUENTIAL TEMPORARY SOURCE-TARGET CONTROL (DECOMP) ========= source - 1 target - 3 PATH 1 - #perturbations: 2 Sequence of the attractors: 1 -> 3 STEP 1 Control set 1: x2=1 x3=1 Control set 2: x1=1 x3=1 PATH 2 - #perturbations: 2 Sequence of the attractors: 1 -> 2 -> 3 STEP 1 Control set 1: x2=1 Control set 2: x1=1 STEP 2 Control set 1: x3=1 execution time of control=0.002 seconds
We use the following command to compute the minimal ASP control from A_{1} to A_{3} for Example 1. The results of ASP control are the same with AST control. To avoid duplication, we omit the output of ASP control here (toy-ASP.txt).
Nodes | Functions | Indices of attractors | Attractors |
---|---|---|---|
x_{1} | f_{1}= x_{2} | A_{1} | 001100 |
x_{2} | f_{2}= x_{1} | A_{2} | 001111 |
x_{3} | f_{3}= (~x_{2}) ∨ x_{4} | A_{3} | 110000 |
x_{4} | f_{4}= x_{3} | A_{4} | 110010 |
x_{5} | f_{5}= (x_{1} ∨ x_{6}) ∧ x_{5} | A_{5} | 111100 |
x_{6} | f_{6}=x_{4} ∧ x_{5} | A_{6} | 111111 |
The first two columns of Table 2 describe a Boolean network with six nodes, including x_{1}, x_{2}, x_{3}, x_{4}, x_{5}, and x_{6}. The model file under BoolNet format is given below.
targets, factors x1, x2 x2, x1 x3, (!x2)|x4 x4, x3 x5, (x1|x6)&x5 x6, x4&x5
The model file under ISPL format is shown below.
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 attractors of Example 2 can be computed using the following command:
Command line: ./cabean -compositional 2 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.003 seconds
Command line: ./cabean -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
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:
R0: R1: x5 R: x4, x6
To compute the minimal OT control from A_{6} to A_{1} without undesired perturbations, we add the option '-rmPert <file name>' to the command line as follows:
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 -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
CABEAN allows users to compute the control for all combinations of source and target attractors by replacing '-sin <indice of the source> -tin <indice of the target>' with '-allpairs' in the command line. The minimal OT control for all pairs of source and target attractors of the example can be computed using the following command line:
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 A_{2} and A_{5} are the undesired ones, we can define them in the file 'rmID.txt' as follows (the indices are separated by comma):
2,5
Taking ASI control as an example, we first show the 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 paths, there are two sequential control paths from A_{6} to A_{1}, where A_{2} and A_{5} act as the intermediate attractors, respectively.
Command line: ./cabean -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
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 -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