BoolODE

Git Repo for converting Boolean models to ODE models and performing stochastic simulations.

Find the documentation for BoolODE at https://murali-group.github.io/Beeline/BoolODE.html.

Usage

python src/BoolODE.py --path=data/test_vars.txt --max-time=5 --num-cells 100

Options

Usage: BoolODE.py [options]

Options:
  -h, --help            show this help message and exit
  --max-time=MAX_TIME   Total time of simulation. (Default = 20)
  --num-cells=NUM_CELLS
                        Number of cells sample. (Default = 100)
  --sample-cells        Sample a single cell from each trajectory? By default
                        will store full trajectory of each simulation (Default
                        = False)
  --add-dummy           Add dummy genes
  -n, --normalize-trajectory
                        Min-Max normalize genes across all experiments
  -i, --identical-pars  Set single value to similar parameters NOTE: Consider
                        setting this if you are using --sample-pars.
  -s, --sample-pars     Sample rate parameters around the hardcoded means ,
                        using 10% stand. dev.
  --std=STD             If sampling parameters, specify standard deviation.
                        (Default 0.1)
  --write-protein       Write both protein and RNA values to file. Useful for
                        debugging.
  -b, --burn-in         Treats the first 25% of the time course as burnin ,
                        samples from the rest.
  --outPrefix=OUTPREFIX
                        Prefix for output files.
  --path=PATH           Path to boolean model file
  --inputs=INPUTS       Path to input parameter files. This is different from
                        specifying a parameter set!
  --pset=PSET           Path to pre-generated parameter set.
  --ics=ICS             Path to list of initial conditions
  --strengths=STRENGTHS
                        Path to list of interaction strengths
  --species-type=SPECIES_TYPE
                        Path to list of molecular species type file.Useful to
                        specify proteins/genes
  -c NCLUSTERS, --nClusters=NCLUSTERS
                        Number of expected clusters in the dataset. (Default =
                        1)
  --max-parents=MAX_PARENTS
                        Number of parents to add to dummy genes. (Default = 1)
  --do-parallel         Run simulations in parallel. Recommended for > 50
                        simulations

Inputs

BoolODE requires a tab separated file containing a Boolean model. The following is a sample input file

Gene	Rule
a	not(c)
c	not(b)
b	not(a)

The first column specifies the Gene, while the second column specifies the Boolean rule governing the expression of the gene. The rules should be formatted as follows: (a_1 or a_2 ... ) and not (r_1 or r_2 ... ) where a_s are the activators, and r_s are the repressors of a given gene.

Outputs

BoolODE produces the following output files:

1. parameters.txt - list of parameters and the corresponding values generated by BoolODE
2. refNetwork.csv - An edgelist with signs of interactions inferred from the model file
3. PseudoTime.csv - BoolODE uses simulated time as a proxy for pseudotime. This file is used as input to BEELINE
4. ExpressionData.csv - The table of gene expression values per 'cell'. For explanation of the format, see below.
5. ClusterIds.csv - A table assigning a cluster ID to each simulated trajectory by carrying out k-means clustering.

Additionally, BoolODE creates a model.py file in src/ with the ODE model to be simulated.

The ExpressionData.csv file has rows corresponding to the genes, and columns corresponding to the timepoints in each experiment. For example, [E0_0,E0_10,E0_20,E1_0,E1_10,E1_20] shows two experiments with 3 timepoints, at times 0,10,20 respectively.

Overview of method

BoolODE is currently designed for transcription factor regulatory networks, though a protein interaction network can be specified by using the --species_type option pointing to a tab separated file indicating the type of each variable, either protein or gene.

For each gene in the TF regulatory network, BoolODE creates two equations, one govering the regulation of the gene (x), and one for its corresponding protein (p).

(\frac{dx}{dt} = m f(X) - l_x x)

(\frac{dp}{dt} = r x - l_p p)

More more details, please see Supplementary section 1 of the preprint.

If you use BoolODE in your research, please cite:

Aditya Pratapa, Amogh Jalihal, Jeffrey Law, Aditya Bharadwaj, and T M Murali. Benchmarking algorithms for gene regulatory network inference from single-cell transcriptomic data, bioRxiv (2019). doi.org/10.1101/642926