Compiling

The ACME is developed in C++. The ACME reads SBML-formatted reaction network files, and parse SBML files using the libSBML C++ package. A SBML file defines all molecular species, reactions schemes, kinetic equations, and parameters in a biological reaction network. Please first install the libSBML C++ package before compiling the ACME. The ACME has been tested successfully compatible with libSBML 3.x. A XML parser package may be required by the libSBML. The xerces-lib 3.1.1 has been tested successfully compatible with libSBML and ACME. 

File format: the initial condition

The ACME requires an initial state (condition) file to enumerate the finite state space. Format of initial condition file is:

6 1
3 0 0 0 0 100, 1

The first line of the initial condition file contains two integer, the first integer is the total number of distinct molecular species in the network, and the second one is the number of states in the initial condition, which is one in most cases. The second line is the initial state, and after comma is the probability associated with the state at time 0. The initial state consists of a number of nonnegative integers separated with space, representing the copy number of each different molecular species in the initial state. The order of numbers in the initial state follows the order of molecular species defined in the SBML file.

Enumerate the state space using buildStateSpace

The buildStateSpace app is for generating the finite state space of a biological reaction network starting from the initial condition.  Below is the command line parameters should be provided. The buildStateSpace app takes into the SBML model file and the initial condition file, and generate the state space and output to a file. 

Usage:

-h --help Prints this help
-m --sbml <sbmlfile> Input SBML file
-i --init <initfile> Initial condition file
-s --statespace <ssfile> Output state space file
-v --verbose Switch for more output

Example:
buildStateSpace -m mToggle.xml -i init.txt -s statespace.txt

 

Generate the transition rate matrix using net2matrix

The net2matrix app is designed to generate the transition rate matrix from finite state space enumerated using the buildStateSpace. The net2matrix takes into the same SBML file and the enumerated state space file, and outputs the sparse transition rate matrix to a coordinate formatted (COO) plain text file.

Usage:

-h --help Prints this help
-m --sbml <sbmlfile> Input SBML file
-s --statespace <ssfile> State space file
-t --omatrix <tmfile> Output transition matrix file
-r --rlabel Put reaction labels aside the matrix entries
-x --reaction <n> About which single reaction you want the matrix to be
-v --verbose 0 Switch for more output

Example:
net2matrix -m mToggle.xml -s statespace.txt -t transmatrix.txt

 

Solving the steady state probability landscapes using the ssor

A number of linear solvers can be used to solve the steady state probability distribution of the dCME.  In the ACME package, we use the Successive Over Relaxation method (SOR) based app: ssor to directly solve the steady state probability landscape. The ssor app takes the transition rate matrix generated using the net2matrix program as the only input, and computes the steady state probability distribution and output to a vector file in plain text format.

Usage:

-h --help Prints this help
-m --mtrx <matrix file> Input matrix file
-s --steady <steady state file> Output steady state distribution file
-o --omega <omega value> Omega value for Succesive Over Relaxation
-t --tol <tolerance> Error tolerance
-v --verbose 0 Switch for more output

Example:
ssor -m transmatrix.txt -s steadystate.txt

 

Compute the time evolution probability landscapes using Expokit-based app mxexp

The mxexp app in the ACME computes the time-evolving probability landscapes of the dCME based on the Expokit package. The mxexp app takes the transition rate matrix generated using the net2matrix program as an input along with the specified the lengths of total time and time interval, and it outputs a probability distribution for each time interval to the specified directory.

Usage:

-m --tm <matrixfile> Input rate matrix file
-t --time 100 Total time for time evolution
-d --dt 10 Time step
-p --p0 <p0file> Initial distribution file
-i --idir <./> Intermediate directory

Example:
mxexp -m transmatrix.txt -t 300000 -d 10 -p inputd1.txt -i ./fptd_dt10/

 

Parse and visualize the probability landscapes

The steady state and time evolution probability distributions computed using the ssor and mxexp apps can be projected into 1D or 2D space of biologically interested molecular species. Simple Perl or Python scripts are included in the ACME package to parse the resulting probability distributions and generate the projected landscapes. These projected landscapes can then be visualized using the plotting scripts and software. All these example scripts are included in the example/scripts folder of the ACME package, and they can be easily adapted to parse and plot different molecular species.

References:

(Please cite following papers for using the ACME method)

1. Youfang Cao, Anna Terebus, and Jie Liang (2016). State space truncation with quantified errors for accurate solutions to discrete chemical master equation. Bulletin of Mathematical Biology. 78:617–661.

2. Youfang Cao, Anna Terebus, and Jie Liang (2016). Accurate Chemical Master Equation solution using multi-finite buffers. SIAM: Multiscale Modeling and Simulation. 14(2): 923–963.

3. Youfang Cao, Hsiao-Mei Lu and Jie Liang (2010). Probability landscape of heritable and robust epigenetic state of lysogeny in phage lambdaProceedings of the National Academy of Sciences USA, 107(43), 18445–18450.

4. Youfang Cao and Jie Liang (2008). Optimal enumeration of state space of finitely buffered stochastic molecular networks and accurate computation of steady state landscape probability. BMC Systems Biology 2:30.