SYSBIONS

SYSBIONS is a computational tool for model selection and parameter inference using nested sampling. It is written in C and provides the facilities to employ GPUs.

sysbions_04.tar

Bioinformatics paper



The full manual is included in the release, including instructions for installation of any dependencies.

To quick-start:

# Download sysbions_04.tar and navigate to the sysbions folder in a terminal window.
# Use the following commands to run a brief example using the supplied repressilator files:
########################################################
# without cuda:
make directory
python parser/makeFiles.py --model repressilator/repressilator.xml --data repressilator/data.txt --fit species1,species3,species5 --var 25
cd DIR_NAME
make sysbions
./sysbions --uniform 0.9 1.1 --uniform 1.9 2.1 --uniform 4.9 5.1 --uniform 950 1050 --constant 1 --nLive 100 --maxIter 500 --e 2
make plots

########################################################
# with cuda:
make directory
python parser/makeFiles.py –model repressilator/repressilator.xml –data repressilator/data.txt –fit species1,species3,species5 –var 25 –cuda
cd DIR_NAME
source /usr/local/bin/usecuda
make sysbionsCuda
./sysbions --uniform 0.9 1.1 --uniform 1.9 2.1 --uniform 4.9 5.1 --uniform 950 1050 --constant 1 --nLive 100 --maxIter 500 --e 2 --cuda 50 512
make plots



# To run a new model:

#### 1. MAKE LIKELIHOOD FUNCTION

    # 1.1) Create directory DIR_NAME (dir_name=DIR_NAME if no name given).
        make directory dir_name=DIR_NAME

    # 1.2) Create files within DIR_NAME directory defining log-likelihood function.
    # Required: header.h and logLhood.c. Optional: logLhood.cu and wrapper.cu.

        # 1.2 a) IF using XML and data files:

        # If necessary, set path to libsbml (see Troubleshooting below)

        # Use script parser/makeFiles.py to parse XML and data files
        # Options:
        # --directory DIR_NAME : optional. Must be as in 1.1. Default: DIR_NAME=DIR_NAME
        # --model FILE_PATH : required (unless option --param supplied). Path to XML file
        # to parse.
        # --data FILE_PATH : required (unless option --param supplied). Path to data file
        # to write likelihood function.
        # --fit SPECIES1,SPECIES2 : optional. Comma-delimited list specifies order of fit of
        # species to data. May include operations such as
        # SPECIES1+SPECIES2. Default: species in order of appearance.
        # --var X : optional. Variance of Gaussian noise of data points. Default:
        # 1.0.
        # --param X : required (unless --model and --data supplied). Number of
        # parameters in model. Default: read from XML file.
        # --cuda : optional. Write likelihood function for use with CUDA.
        python parser/makeFiles.py --directory DIR_NAME --model repressilator/repressilator.xml --data repressilator/data.txt --fit species1,species3,species5 --var 25 -param 5 --cuda

    # 1.2 b) ELSE Copy the templates into the new directory, removing the qualifier ‘_template’.
    # Edit the header file, specifying the number of parameters (NPARAM XXX) and whether or
    # not to use CUDA. Edit logLhood.c (and wrapper.cu and logLhood.cu) where appropriate.

#### 2. Change directory to DIR_NAME
    cd DIR_NAME

#### 3. COMPILE CODE

    # Creates executable sysbions and the results folder. If CUDA was specified in Step 1.2, go to 3 a.
    # Else, go to 3 b.

    # 3 a) IF using CUDA
        # If necessary, set path to CUDA e.g.
        source /usr/local/bin/usecuda
        # Open Makefile and edit paths to libraries as necessary.
        # The resulting executable will be compatible with both C and CUDA functions.
        # Requires logLhood.cu, wrapper.cu, logLhood.c and header.h.
        make sysbionsCuda

    # 3 b) ELSE make sysbions to compile sysbions.c without any CUDA compatibility or requirements.
        # Requires logLhood.c and header.h.
        make sysbions

#### 4. RUN

    # 4.1 Set paths

        # 4.1 a) IF CUDA If necessary, set paths to cublas and gsl_odeiv2 (see Troubleshooting below)

        # 4.1 b) ELSE If necessary, set path to gsl_odeiv2 (see Troubleshooting below)

    # 4.2 Run sysbions

        # to print options:
        ./sysbions

        # e.g.:
        ./sysbions --uniform 0.9 1.1 --uniform 1.9 2.1 --uniform 4.9 5.1 --uniform 950 1050 --constant 1 --nLive 100 --maxIter 50 --e 2

        ./sysbions --uniform 0.9 1.1 --uniform 1.9 2.1 --uniform 4.9 5.1 --uniform 950 1050 --constant 1 --nLive 100 --maxIter 50 --e 2 --cuda 10 512

#### 5. PLOT

    # The posterior is sampled and stored in _results_posterior.txt (or [ROOT]_posterior.txt, where [ROOT] was given at the command line).
    # The following command creates scatterplots (a PNG file with the same name as the TXT file) of all parameter relationships from the given posterior file:
    make plots file_name=_results_posterior.txt



Input options:

    Input parameters sequentially in order of appearance in the XML/likelihood file as
        --uniform N1 N2
    where N1 is the lower limit and N2 the upper limit or as
        --constant N
    where N is the value of the constant parameter.
    Input number of live points N as
        --nLive N
    Input number of iterations N as
        --maxIter N
    or specify the tolerance as
        --tol N
    where N is the difference between the cumulative evidence and the amount added at which the algorithm exits.
    Use CUDA to perform N1 iterations in parallel using N2 threads as
        --cuda N1 N2
    Jump N points in a single iteration without CUDA using
        --nLeap N
    Select a mode, rejection, random walk, or ellipsoidal (with expansion factor N e.g. 3), as
        --r
        --rw
        --e N
    Restart from saved points and information files with
        --restart _restart_points.txt _restart_input.txt
    Specify root of files to which to save points and information with
        --write_restart _restart
    Specify root of results files with
        --results _results
    Specify number of points to store in posterior sample with
        --nPosterior N
    where N < 0 will store the maximum possible number.
    Specify number of trajectories to store with
        --nTrajectory N

e.g.
    ./sysbions --uniform 0 1 --uniform 10 20 --nLive 100 --maxIter 500 --e 2 --cuda 10 512



Troubleshooting

Some paths may have to be set for the program to run. To temporarily set an environment variable, use setenv for cshell, set for tcshell or export for bash. To set a new path:
    setenv LD_LIBRARY_PATH /path/to/lib # cshell
    set LD_LIBRARY_PATH = (/path/to/lib) # tcshell
    export LD_LIBRARY_PATH=/path/tol/lib # bash

To add to an existing path:
    setenv LD_LIBRARY_PATH /path/to/lib/:$LD_LIBRARY_PATH # cshell
    set LD_LIBRARY_PATH = (/path/to/lib/ $LD_LIBRARY_PATH .) # tcshell
    export LD_LIBRARY_PATH=/path/to/lib/:$LD_LIBRARY_PATH # bash


PYTHON IMPORT ERROR: LIBSBML: NO SUCH MODULE

    # If not installed, you need to install libsbml according to your python version (http://sourceforge.net/projects/sbml/files/libsbml/5.8.0/stable/)
    # If installed, you need to set the path to it.

NVCC: COMMAND NOT FOUND

    # You need to install nvidia CUDA (https://developer.nvidia.com/cuda-downloads)
    # When installed, you may need to mount it with e.g.
    source /usr/local/bin/usecuda # cshell

SYMBOL LOOKUP ERROR: gsl_odeiv2_step_rk8pd

    # If not installed, you need to install gsl version 1.15 or higher (http://www.gnu.org/prep/ftp.html)
    # If installed, you need to set the path to it (e.g. /usr/local/lib64).

UNDEFINED REFERENCES TO CUDA FUNCTIONS

    # Ensure that a path is set to it (e.g. /usr/local/cuda/lib64:/usr/local/cuda/lib/)


Please report any bugs to rj411@imperial.ac.uk.