mcmc clib

a C program for simplified manifold Metropolis adjusted Langevin algorithm (smmala) sampling of ordinary differntial equation (ode) model parameters

Project maintained by a-kramer (mail) Hosted on GitHub Pages — Theme by mattgraham

This software's characteristics

  • accepts unnormalized data and reference data (arbitrary units)
  • command line tool
  • samples in logarithmic space
  • multivariate Gaussian prior densities only (in logspace)
  • aimed at HPC use
    • parallel tempering scheme using MPI
    • parallel simulation of all experiment setups using OpenMP
  • uses hdf5 for the storage of experimental data and resulting parameter sample
  • uses CVODES solver to obtain numerical solutions to the model's initial value problems
    • forward sensitivity analysis
    • Fisher information

Flowchart

This software can be used together with other tools such as the R package SBtabVFGEN and VFGEN itself. This Flowchart shows and example workflow.

SBtab->vfgen->gcc->model.so->ode_smmala

But, the input files to ode_smmala can be made using any other tool set, as long as the contents adhere to the same structure.

Alternatives

The software is not developed by a team and new features are added very slowly. Perhaps the biggest drawback is that we do not provide any automated build system yet. Compiling is done by inspecting and changing the Makefile from tamplates, manually. Fot these reasons, it may be better to use an alternative like GNU MCsim or the matlab packages PESTO & AMICI, or perhaps even an alternatuve methodology like the profile likelihood method.

General Installation Instructions

The Software uses a shared library as model. Any way to create the shared library will work. We use the vfgen tool for these purposes. The experimental data is stored in hdf5 files with agrred upon annotation. The naming rules are listed in the documentation. This file can be generated using any software that supports hdf5 output (e.g. Matlab, R, python). But, we also provide a program for the conversion of data from SBtab (tsv) files into an hdf5 file.

In principle, if a software that can transform an sbml model into cvodes compatible sources exists, then it can, of course, also be used here.

For the handling of models, we use the SBtab file format (but not any of the tools provided by the authors). We use a custom R package SBtabVFGEN to translate models from an OpenDocument Spreadsheet format or a set of TSVs (tab separated value files, text) into a vfgen vf file. The DemoModel repository is an example of how we store and process models using this SBtab→R→vfgen→C workflow. Vfgen calculates the rhs vector field's jacobian (analytically).

Simulations

The sampler repeatedly solves the initial value problem specified in such a way as to replicate the experimental data and normalises the result in the same way as in the experiment's description. This way arbitrary scale constants are cancelled. The simulations are done via the sundials cvodes solver.

	  
	    External library dependencies
	    For ODE solutions:
              Sundials CVODES 2.7.0
	    
	    For MCMC:
              GSL 
              CBLAS
	      OpenMPI
	      (OpenMP)

	    For VFGEN:
	      GiNaC 
	      mini XML

Installation Instructions

Here are some more detailed instructions for installation on Gentoo, Arch, OpenSUSE, and Ubuntu.

In principle, it is possible to compile the sources on a windows system. We provide no binary releas. In addition, since this software is aimed at HPC use, we strongly discourage this.

Makefile

As mentioned earlier, we don't use an automated build system.

Inspect the Makefile (Makefile.ubuntu). You can use it as a starting point. The bundled Makefile builds the vfgen executable as well as the sampler.

Afterwards, use the Makefile by typing

make

Short Usage Hints

mpirun -N 10 ./ode_smmala -l ./model.so -d ./experimental-data.h5 -o sample.h5 -s $((3*10**4))

The data file includes the measurement time specifications, the data, the standard deviation of observations and the hyperparameters μ and Σ of the Gaussian prior. This is discussed in the package documentation.

Hints

you can load the resulting sample using any hdf5 reading script language or simly h5dump. GNU Octave can read the sample files using the load function: load mcmc_rank_00_of_8_sample.h5.