
HOW TO use this set of programs to generate state space, transition matrix and 
compute the steady state landscape distribution.

Aug. 20, 2007

1. Running Environments

This set of programs was developed under Linux operating system, and compiled
with gcc-4.1.2. In the steadystate program, ARPACK and Arpack++ packages are 
used to compute eigenvalues and eigenvectors. ARPACK and Arpack++ could be downloaded
from our website. ARPACK is compiled under gcc-3.3.6 with g77 fortran compiler,
and steadystate program is compiled with gcc-4.1.2 and linked with gcc-3.3.6
compiled ARPACK libs.


2. The descriptions of functions of programs.

(1) buildStateSpace

This program is used to generate a state space from a biological network model
and a given initial condition. Biological model is a file based on SBML framework,
which involves molecular special, reactions and all necessory parameters in it.
The initial condition is also given in a file, the format is described below.

eg:
$cat pdv-eg.txt
6 1
3 0 0 0 0 0, 1

The first line of the initial condition file contains two integer, the first one
is the number of molecular species, the second one is the number of the initial
states, it'll be one in most cases. The second line of this file is the initial
state and the probability of this state in the initial time. They are seperated
with a comma and whitespace. The initial state consists of n integers, n is the
first integer in the first line, and they are also seperated with whitespaces.
The numbers in the initial state represent the copy number of each molecular
species in the model. The sequence of numbers in the initial state is corresponding
to the sequence of molecular species in the SBML model.

To run this program, some necessary command line parameters should be provided.

Usage:
buildStateSpace -m [SBML filename] -i [initial condition file] -s [state space filename]

  [SBML filename]:          This is for the file name of the biomodel in SBML format.
  [initial condition file]: contains an initial state in it.
  [state space filename]:   the output filename of State Space.

For example:
buildStateSpace -m mToggle.xml -i pdv_4.txt -s ss_4.txt

The program buildStateSpace2 is another version of buildStateSpace. They are all 
same but the variable length used to store the state space. buildStateSpace uses
unsigned char, which occupies only one byte of space, but buildStateSpace2 uses
unsigned short int to store, which occupies two bytes. buildStateSpace can be used
only to compute those state spaces, in which all copy numbers are less than 255.
While buildStateSpace2 can compute at most 65535 copies of molecules in a system.


(2) net2matrix

This program is used to generate the transition matrix from a state space produced
by buildStateSpace and a SBML biomodel.

Usage:
net2matrix -m [SBML filename] -s [state space filename] -t [matrix filename]

[SBML filename]:        This is for the file name of the biomodel in SBML format.
[state space filename]: the file name of existing state space.
[matrix filename]:      the output filename of transition matrix.

For example:
net2matrix -m mToggle.xml -s ss_4.txt -t tm_4.txt

(3) steadystate

This program is intended to compute the steady state landscape distribution of
a biological model. The only input is the transition matrix produced by net2matrix
program.

Usage:
steadystate [Matrix file generated by net2matrix]

For example:
steadystate tm_4.txt > steady_4.txt


(4) parseResult-sstoggle, parseResult-ssMAPK

This group of programs are aimed to parse the results of steadystate, and output
a formated, tabbed text file for the convience of visualization later. 

Usage:
parseResult-sstoggle  [result filename] [state space filename] [time steps] [significance threshold]

For example:
parseResult-sstoggle steady_4.txt ss_4.txt 1 0 > result.dat


3. Visualization

To now, the state space, transition matrix, and steady state distribution are all 
obtained. The next step is to visualize the result data generated by parseResult
programs. R package or SigmaPlot etc. can all be used to do this.



