Skip to content

Commit

Permalink
Update documentation for Python interface (#1208)
Browse files Browse the repository at this point in the history 
* Add PySB import, PEtab import, plain ODEs (Closes #654)
* Cleanup
* Update
  • Loading branch information
@dweindl
dweindl authored Aug 19, 2020
1 parent 0d05764 commit 6dfa1f8
Showing 1 changed file with 108 additions and 45 deletions.
153 changes: 108 additions & 45 deletions documentation/PYTHON.md
View file
Original file line number Diff line number Diff line change
@@ -1,87 +1,150 @@
# Python Interface {#python_interface}

In the following we will give a detailed overview how to specify models in Python and how to call the generated simulation files.
In the following we will give a detailed overview how to specify models in
Python and how to call the generated simulation files.

## Model Definition

This guide will guide the user on how to specify models in Python using SBML. For example implementations see the examples in the python/examples directory.
This guide will guide the user on how to specify models to import and simulate
them using the Python interface.
For example implementations see the examples in the `python/examples`
directory.

### SBML input
### SBML import

First, import an sbml file using the `amici.sbml_import.SbmlImporter` class:
[SBML](http://sbml.org/) is a commonly used format for specifying systems
biology models. To import an SBML model into AMICI, first, load an SBML file
using the `amici.sbml_import.SbmlImporter` class:

import amici
sbmlImporter = amici.SbmlImporter('model_steadystate_scaled.sbml')

the sbml document as imported by [libSBML](http://sbml.org/Software/libSBML) is available as
sbml_importer = amici.SbmlImporter('model_steadystate_scaled.sbml')

sbml = sbmlImporter.sbml
the SBML model as imported by [libSBML](http://sbml.org/Software/libSBML)
is available as

### Constants
sbml_model = sbml_importer.sbml

parameters that should be considered constants can be specified in a list of strings specifying the respective SbmlId of a parameter.
#### Constants

constantParameters=['k4']
Model parameters that should be considered constants can be specified in a list
of strings specifying the SBML ID of the respective parameter, e.g.:

### Observables
constant_parameters=['k4']

Assignment rules that should be considered as observables can extracted using the `amici.assignmentRules2observables` function.
#### Observables

Observables are specified as a dictionary with observable ID as key and
observable formula as value.

A convenient way for specifying observables for an SBML model is storing them
as `AssignmentRule`s. Assignment rules that should be considered as observables
can then be extracted using the `amici.assignmentRules2observables` function,
e.g.:

observables = amici.assignmentRules2observables(sbml, filter_function=lambda variable:
variable.getId().startswith('observable_') and not variable.getId().endswith('_sigma'))

### Standard Deviations
#### Standard Deviations

standard deviations can be specified as dictionaries ...
Standard deviations can be specified as dictionaries ...

sigmas = {'observable_x1withsigma': 'observable_x1withsigma_sigma'}


## Model Compilation
#### Model Compilation

to compile the sbml as python module, the user has to call the method `amici.sbml_import.SbmlImporter.sbml2amici`, passing all the previously defined model specifications
To generate a Python module from the SBML model, call the method
`amici.sbml_import.SbmlImporter.sbml2amici`, passing all the previously defined
model specifications:

sbmlImporter.sbml2amici('test', 'test',
observables=observables,
constantParameters=constantParameters,
sigmas=sigmas)
sbml_importer.sbml2amici('test', 'test',
observables=observables,
constant_parameters=constant_parameters,
sigmas=sigmas)

Note: To build AMICI with OpenMP support, which allows to parallelize model simulations of multiple
experimental conditions, set the environment variables `AMICI_CXXFLAGS` and `AMICI_LDFLAGS` to the
correct OpenMP flags of your compiler and linker, respectively. This has to be done for both AMICI
package installation *and* model compilation. When using `gcc` on Linux, use:
### PySB import

# on your shell:
AMICI_CXXFLAGS=-fopenmp AMICI_LDFLAGS=-fopenmp pip3 install amici
[PySB](http://pysb.org/) is a tool for specifying rule-based systems biology
models as Python code. AMICI can import PySB models via
[`amici.pysb_import.pysb2amici`](https://amici.readthedocs.io/en/latest/generated/amici.pysb_import.html#amici.pysb_import.pysb2amici).

# in python, before model compilation:
import os
os.environ['AMICI_CXXFLAGS'] = '-fopenmp'
os.environ['AMICI_LDFLAGS'] = '-fopenmp'
[BioNetGen](https://www.csb.pitt.edu/Faculty/Faeder/?page_id=409) and
[Kappa](https://kappalanguage.org/) models can be imported into AMICI using
PySB.

### PEtab import

[PEtab](https://github.com/PEtab-dev/PEtab) is a format for specifying
parameter estimation problems. It is based on an SBML model and tab-separated
value files specifying the observation mdoel and experimental conditions.

AMICI can import PEtab-based model definitions and run simulations for the
specified simulations conditions. For usage, see
[python/examples/example_petab/petab.ipynb](https://github.com/AMICI-dev/AMICI/blob/develop/python/examples/example_petab/petab.ipynb).

### Importing plain ODEs

The AMICI Python interface does not currently support direct import of ODEs.
However, it is straightforward to encode them as RateRules in an SBML model.
The [yaml2sbml](https://github.com/martamatos/yaml2sbml) package may come in
handy, as it facilitates generating SBML models from a YAML-based specification
of an ODE model. Besides the SBML model it can also create
[PEtab](https://github.com/PEtab-dev/PEtab) files.

## Model Simulation

currently the model folder has to be manually added to the python path

AMICI model import creates a Python module for simulation of the respective
model. To use the model module, the model directory has to be manually added to
the python path:

import sys
sys.path.insert(0, 'test')

the compiled model can now be imported as python module

import test as modelModule

to obtain a model instance call the `getModel()` method. This model instance will be instantiated using the defautl parameter values specified in the sbml.
the compiled model can then be imported as

import test as model_module

It is usually more convenient to use `amici.import_model_module()` for that
purpose.

To obtain a model instance call the `getModel()` method. This model instance
will be instantiated using the default parameter values specified in the
imported model:

model = modelModule.getModel()
model = model_module.getModel()

then pass the simulation timepoints to `amici.Model.setTimepoints`
Specify the simulation timepoints via `amici.Model.setTimepoints`:

model.setTimepoints(np.linspace(0, 60, 60))
for simulation we need to generate a solver instance

For simulation, we need to generate a solver instance:

solver = model.getSolver()
the model simulation can now be carried out using `amici.runAmiciSimulation`

The model simulation can now be carried out using `amici.runAmiciSimulation`:

rdata = amici.runAmiciSimulation(model, solver)

## Building models with OpenMP support

AMICI can be built with OpenMP support, which allows to parallelize model
simulations for multiple experimental conditions.

On Linux and OSX this is enabled by default. This can be verified using

import amici
amici.compiledWithOpenMP()

If not already enabled by default, you can enable OpenMP support by setting
the environment variables `AMICI_CXXFLAGS` and `AMICI_LDFLAGS` to the
correct OpenMP flags of your compiler and linker, respectively. This has to be
done for both AMICI package installation *and* model compilation. When using
`gcc` on Linux, this would be:

# on your shell:
AMICI_CXXFLAGS=-fopenmp AMICI_LDFLAGS=-fopenmp pip3 install amici

# in python, before model compilation:
import os
os.environ['AMICI_CXXFLAGS'] = '-fopenmp'
os.environ['AMICI_LDFLAGS'] = '-fopenmp'

0 comments on commit 6dfa1f8

Please sign in to comment.