Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Python interface for Gillespie-style biochemical simulations

Project description

GillesPy2 is a Python package for stochastic simulation of biochemical systems. It offers an object-oriented approach for creating mathematical models of biological systems, as well as a variety of methods for performing time simulation of those models. The methods include the Gillespie direct method (SSA), several variant stochastic simulation methods including tau-leaping, and numerical integration of ODEs. The solvers support a variety of user environments, with optimized code for C++, Cython, and NumPy. GillesPy2 also supports SBML.

PLEASE REGISTER AS A USER, so that we can prove GillesPy2 has many users when we seek funding to support development. GillesPy2 is part of the StochSS project.

PyPI PyPI - License PyPI - Python Version

Table of contents

Installation

GillesPy2 can be installed on your computer using different methods, as described below.

Using PyPI

On Linux, macOS, and Windows operating systems, you should be able to install GillesPy2 with pip. If you don't have the pip package or are uncertain, first run the following command in a terminal command line interpreter:

sudo python3 -m ensurepip

Then, to install GillesPy2 from the Python package repository, run the following command:

python3 -m pip install gillespy2 --user --upgrade

Using the source code repository

As an alternative to getting it from PyPI, you can instruct pip to install GillesPy2 directly from the GitHub repository:

python3 -m pip install git+https@github.com:GillesPy2/GillesPy2.git --user --upgrade

As a final alternative, you can first use git to clone a copy of the GillesPy2 source tree from the GitHub repository to your local computer disk, and then install GillesPy2 using that copy:

git clone --recursive https@github.com:GillesPy2/GillesPy2.git
cd GillesPy2
python3 -m pip install  .  --user --upgrade

Usage

GillesPy2 provides simple object-oriented abstractions for defining a model of a biochemical system and simulating that model using efficient stochastic simulation algorithms. The basic steps to use GillesPy2 are:

  1. Create a GillesPy2.Model containing molecular species, parameters, and reactions (or import it from an SBML file)
  2. Invoke the model's .run() method.

The run() method can be customized using keyword arguments to select different solvers, random seed, data return type and more. For more detailed examples on how to use GillesPy2, please see the Getting Started Jupyter notebook contained in the examples subdirectory.

Simple example to illustrate the use of GillesPy2

Dimerization is a process in which two molecules of some molecular species (known as a "monomer" in this situation – let's call it "M" for short) come together to create a new molecule (call it "D"), but do so in a way that is reversible, meaning the combined structure can also decay or dissociate back into "M". A simple model of the dimerization process represents it as two reactions: a reaction in which one molecule of "M" reacts with another molecule of "M" to form one new molecule ("D"), and another reaction in which a molecule of "D" breaks apart into two molecules of "M". In terms of biochemical reactions, it looks like this (where kc and kd represent the rate constants for creation and dissociation of the dimer, respectively; M represents the number of molecules of "M"; and D is the number of molecules of "D"):

     kc
2 M  ⟷ D
     kd

In GillesPy2, a model is expressed as an object having the parent class Model. Components of the model, such as the reactions, molecular species, and characteristics such as the time span for simulation, are all defined within the subclass definition. The following Python code represents our dimerization model using GillesPy2's facility:

class Dimerization(gillespy2.Model):
    def __init__(self, parameter_values=None):
        # First call the gillespy2.Model initializer.
        gillespy2.Model.__init__(self, name='Dimerization')

        # Define parameters for the rates of creation and dissociation.
        k_c = gillespy2.Parameter(name='k_c', expression=0.005)
        k_d = gillespy2.Parameter(name='k_d', expression=0.08)
        self.add_parameter([k_c, k_d])

        # Define variables for the molecular species representing M and D.
        m = gillespy2.Species(name='monomer', initial_value=30)
        d = gillespy2.Species(name='dimer',   initial_value=0)
        self.add_species([m, d])

        # The list of reactants and products for a Reaction object are each a
        # Python dictionary in which the dictionary keys are Species objects
        # and the values are stoichiometries of the species in the reaction.
        r_c = gillespy2.Reaction(name="r_creation", rate=k_c, reactants={m:2}, products={d:1})
        r_d = gillespy2.Reaction(name="r_dissociation", rate=k_d, reactants={d:1}, products={m:2})
        self.add_reaction([r_c, r_d])

        # Set the timespan for the simulation.
        self.timespan(numpy.linspace(0, 100, 101))

Given the class definition above, the model can be simulated by first instantiating the class object, and then invoking the run() method on the object. The following code will run the model 10 times to produce 10 sample trajectories:

model = Dimerization()
results = model.run(number_of_trajectories=10)

The results are then stored in a class Results object for single trajectories, or a class Ensemble object for multiple trajectories. Results/Ensembles can be plotted with matplotlib using plot() or in plotly (offline) using plotplotly(). For additional plotting options such as plotting from a selection of species, or statistical plotting, please see the documentation.:

results.plot()

Alternatively, the results object inherits python-builtin UserDict for single trajectories, and UserList for multiple trajectories. Results can be plotted easily using any plotting library such as matplot lib as shown below:

for index in range(0, 10):
    trajectory = results[index]
    plt.plot(trajectory['time'], trajectory['monomer'], 'r')
    plt.plot(trajectory['time'], trajectory['dimer'],   'b')

With a few additional Python Matplotlib commands to create figure labels and such, we end up with a plot like this:

Getting help

GillesPy2's online document provides more details about using the software. If you find any problem with GillesPy2 or the documentation, please report it using the GitHub issue tracker for this repository. You can also contact Dr. Brian Drawert directly with questions and suggestions.

Contributing

We would be happy to receive your help and participation with enhancing GillesPy2! Please follow the guidelines described in CONTRIBUTING.md.

License

GillesPy2 is licensed under the GNU General Public License version 3. Please see the file LICENCE for more information.

Authors and history

New developments happen primarily in the develop branch. New releases are put in the master branch.

Master Branch Develop Branch Coverage
Build Status Build Status Coverage

Acknowledgments

This work has been funded by National Institutes of Health (NIH) NIBIB Award No. 2R01EB014877-04A1.

GillesPy2 uses numerous open-source packages, without which it would have been effectively impossible to develop this software with the resources we had. We want to acknowledge this debt. In alphabetical order, the packages are:

  • Jupyter – web application for creating documents containing code, visualizations and narrative text
  • libSBML – a library for reading, writing, and manipulating SBML content
  • lxml – an XML parsing library for Python
  • MatplotLib – Python 2D plotting library
  • Numpy – the fundamental package for scientific computing with Python
  • Scipy – Python-based ecosystem of open-source software for mathematics, science, and engineering

Finally, we are grateful for institutional resources made available by the UNC Asheville, the University of California at Santa Barbara, Uppsala University, and the California Institute of Technology.

           

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for gillespy2, version 1.2.1
Filename, size File type Python version Upload date Hashes
Filename, size gillespy2-1.2.1-py3-none-any.whl (74.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size gillespy2-1.2.1.tar.gz (60.8 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page