Tellurium: An Extensible Python-based Modeling Environment for Systems and Synthetic Biology

Abstract

Here we present Tellurium, a Python-based environment for model building, simulation, and analysis that facilitates reproducibility of models in systems and synthetic biology. Tellurium is a modular, cross-platform, and open-source simulation environment composed of multiple libraries, plugins, and specialized modules and methods. Tellurium is a self-contained modeling platform which comes with a fully configured Python distribution. Two interfaces are provided, one based on the Spyder IDE which has an accessible user interface akin to MATLAB and a second based on the Jupyter Notebook, which is a format that contains live code, equations, visualizations, and narrative text. Tellurium uses libRoadRunner as the default SBML simulation engine which supports deterministic simulations, stochastic simulations, and steady-state analyses. Tellurium also includes Antimony, a human-readable model definition language which can be converted to and from SBML. Other standard Python scientific libraries such as NumPy, SciPy, and matplotlib are included by default. Additionally, we include several user-friendly plugins and advanced modules for a wide-variety of applications, ranging from complex algorithms for bifurcation analysis to multidimensional parameter scanning. By combining multiple libraries, plugins, and modules into a single package, Tellurium provides a unified but extensible solution for biological modeling and analysis for both novices and experts. Availability: tellurium.analogmachine.org

Background

Python has proven to be a very popular language for scientific computing and data science. The ease of learning and use, coupled with the open-source nature of the language has made it an ideal platform for scientific computations. The systems and synthetic biology community have shown support for Python through the development of a variety of simulation tools. These include PySCeS [22] with a focus on simulation via differential equations, structural analysis, and metabolic control analysis; SloppyCell [21], with a focus on model fitting and calculating the resulting uncertainties; pySB [20], with a focus on rule-based reaction models; or COBRApy [14], with a focus on constraint-based modeling. However, as can be observed from this brief overview, most tools are limited in their scope and focus on a specific set of functionalities. Additionally, the installation process of systems biology software can often be quite cumbersome, requiring users to follow multiple and often fragile steps for proper configuration. This can be problematic for both novices and experts in the field.

Another critical issue in systems and synthetic biology is ensuring exchangeability and reproducibility of models and simulation setups. Over the past few years, the community has developed a variety of standards to accurately capture models and simulation experiments. These standards include the Systems Biology Markup Language (SBML) [17], which encodes the model, Simulation Experiment Description Markup Language (SEDML) [30], which encodes the simulation setup, and the COMBINE archive [5], which is the collection of files that represent the full description of the model and associated simulation experiments. For synthetic biology, the community has developed the Synthetic Biology Open Language (SBOL) to describe synthetic designs [2]. Many of the existing tools support at least part of these standards. For example, PySCeS supports SBML and a large portion of SED-ML. SloppyCell also supports SBML, as does COBRApy. pySB offers some support for reading and writing SBML models. However, none of the Python tools described here supports the full set of standards discussed above.

Therefore, our goal in developing Tellurium was to design a general platform with broader scope by combining a large variety of third-party tools while supporting various standards to ensure reproducibility. Furthermore, the installation process should be as simple as possible to make our tool easily accessible.

The core philosophy behind Tellurium is to provide a high-performance platform accessible to both novices and experts. We bring together a wide variety of libraries and tools for researchers in systems and synthetic biology. Tellurium is distributed using one-click installers so the installation process is extremely simple. Tellurium provides a convenient one-stop solution for many of the needs of the community, which is especially helpful for novices who do not wish to deal with the complexities of manual configuration of the various tools we distribute. For systems biology modeling, Tellurium supports various modeling standards including SBML, SED-ML, the COMBINE archive, and SBOL. In addition, we distribute libRoadRunner [28] for simulation, AUTO2000 [13] for bifurcation analysis, and Antimony [27], phraSED-ML [12], as well as SimpleSBML [9] for streamlined model creation and modification. Along with the tools distributed with Tellurium, we provide a simple method for users to install additional Python packages, making Tellurium highly extensible.

Implementation

Tellurium is implemented in a mixture of C, C++, and Python. The software can be roughly partitioned into three functional pillars: i) standards support; ii) modeling; and iii) general utilities (Figure 1).

Figure 1:

Overview of Tellurium. Tellurium is composed of three distinct functional pillars including standards support, modeling support, and utilities. Several third-party Python packages come with Tellurium and additional packages can be installed if needed.

Support for standards in systems and synthetic biology is included in Tellurium via the respective libraries such as libSBML [8], libSEDML [4], libCOMBINE [6], libSBOL, and basic support for CellML [16] via Antimony. Many of these libraries come from third-party developers and some have been augmented for Tellurium to make them easier to use. For example, SimpleSBML simplifies model building instead of requiring users to use low-level methods in libSBML. Tellurium provides extensive layers to libSBML and libCOMBINE to simplify the process of generating COMBINE archives. We use COMBINE archives to facilitate simulation reproducibility.

The second pillar includes the modeling and numerical support for model design and analysis. Tellurium comes with packages such as Antimony [27] and phraSED-ML [12] which translate model and simulation setup in SBML and SED-ML format to human-readable counterparts. The numerical support includes libRoadRunner which provides a variety of analyses including ordinary differential equation simulation, Gillespie-based stochastic simulation, metabolic control analysis, and structural analysis of networks via libStructural [3].

Another important function included in Tellurium is bifurcation analysis, crucial for understanding models with multiple steady states. This type of analysis can be difficult for a novice to perform, so a wrapper to AUTO2000 is provided which interfaces itself to libRoadRunner. By implementing it as a plugin for libRoadRunner, AUTO2000 can directly access the simulation engine and perform computations without the overhead of a cross-language API. This also means that the bifurcation tool can be used outside of Python and hosted by other tools. Note that unlike other AUTO2000 implementations, our implementation does not require an external compiler because this task is handled by libRoadRunner.

Finally, to demonstrate the flexibility in a Python ecosystem, we also bundle COBRApy, which is one of the primary constraint-based modeling packages. In addition, common Python packages that are essential in scientific computing are bundled with Tellurium. These include, but are not limited to, SciPy and NumPy (for a large variety of numerical methods), SymPy (for symbolic manipulation), and plotting libraries such as matplotlib and seaborn. Supplementary Table S1 lists short descriptions of the packages discussed in this manuscript.

Tellurium is distributed with two interfaces: The first is Tellurium Spyder, which is based on Spyder IDE and provides a MATLAB-like environment for researchers who are already familiar with editor/console type programming. Spyder IDE is a Python-based development environment that comes with powerful tools like profiler and static code analysis. Spyder IDE is ideal for modelers and developers who prefer generating and debugging raw Python scripts. For those who prefer notebook-like interfaces, we provide a Jupyter notebook-based version called Tellurium Notebook. Jupyter notebook differs from Spyder IDE as it creates documents containing live code, plots, narrative texts, and equations. Moreover, Jupyter notebooks are interactive, making it ideal for sharing and displaying the work with others. It is also possible to install Tellurium and its dependencies in an existing Python environment through pip. Examples of alternative hosts that have employed Tellurium include PyCharm and Sublime Text.

Applications

In this section, we illustrate several use cases of Tellurium. In particular, we demonstrate various tools included in Tellurium as well as its ability to integrate with other Python packages. We present examples of model building, simulation, and subsequent analysis tasks such as metabolic control analysis, bifurcation analysis, and parameter estimation. All scripts used in this section are available in the Supplementary Materials.

Model Building and Simulation

First, we start with a simple example demonstrating model building and simulation in Tellurium. Models in Tellurium can be defined using Antimony, a human-readable model definition language which directly translates to SBML. Antimony supports a large part of SBML specification including events and assignment rules and can be easily translated to and from SBML. Figure 2 illustrates a model of a simple linear chain involving five floating species and corresponding simulation result.

Figure 2:

A simple linear chain model with five floating species written in Antimony language and corresponding simulation result. The diagram below illustrates the model. Species X_o is a boundary species (fixed) and each reaction is modeled using reversible mass-action kinetics. J_i is used to label each reaction.

Metabolic Control Analysis

An important part of the modeling and model analysis process is sensitivity analysis, which provides information about the effect of system parameters and states on the results. A standard approach for sensitivity analysis is metabolic control analysis (MCA). Tellurium calculates the various elasticities and coefficients defined in MCA [19, 24] using libRoadRunner [28]. In addition, there is support for frequency dependent MCA in the form of Bode plots [18]. A number of utilities are provided to make it easier to visualize results from MCA studies. In particular, we provide utilities to help visualize flux control, concentration control, and elasticity profiles using heat maps. Figure 3 shows heatmaps of the distribution of flux and concentration control coefficients in a linear pathway of six reactions (Figure 2).

Figure 3:

Two heatmaps showing the flux and concentration control coefficients for a linear reaction chain of six reactions and five floating species illustrated in Figure 2. E_i is the enzyme level for reaction i, and J_i is the flux through reaction i. S_i is the substrate label. Red indicates positive values and blue indicates negative values. For example, reaction step six, E₆, has a strong negative influence on species S₅.

Bifurcation Analysis

Bifurcation analysis enables qualitative changes in model behavior to be studied as a function of a model parameter. Such qualitative changes include bistability and oscillatory behavior [1, 15]. Tellurium’s bifurcation facility is designed to automatically compute a bifurcation in parameter space and plot a bifurcation diagram without user intervention. The user specifies a model parameter as the basis for the analysis. The bifurcation tool will then automatically scan a user-specified range of parameter values. If at some point the system changes to an alternate stationary state, the bifurcation is recorded and scanning continues. Figure 4A illustrates a number of bifurcation changes in a model of the embryonic stem cell switch [11] with Tellurium. For models where the stoichiometry matrix does not have full rank, libRoadRunner creates the appropriately reduced model [7] thus permitting bifurcation analysis of protein signaling networks to be carried out [25, 23].

Figure 4:

Plots depicting applications of Tellurium. A) Bifurcation analysis applied to a model of an embryonic stem cell switch. The label LP represents a fold or turning point bifurcation. Blue, green, red, and yellow indicate transcription factors OCT4, SOX2, NANOG, and OCT4–SOX2 heterodimer respectively. Blue (OCT4) trace is covered by the green trace (SOX4). B) Central carbon metabolism model of E. coli fitted against experimental data of 9 metabolites. Lines represent simulated data using fitted parameters and dots represent the experimental data. Red, blue, green, purple, orange, yellow, brown, pink, and gray traces and dots corresponds to pep, g6p, pyr, f6p, glcex, g1p, pg, fdp, and gap, respectively.

COMBINE Support

Tellurium supports importing and exporting COMBINE archives through the Antimony and phraSED-ML languages. To demonstrate this feature, we present a simple application using the same model and simulation setup as in the code illustrated in Figure 2. To generate a COMBINE archive, a model and a simulation setup are defined in the Antimony and phraSED-ML language. We then create an inline OMEX by joining the two string blocks.

import tempfile, os
import tellurium as te
te.setDefaultPlottingEngine(′matplotlib′)
antimony_str = ′′′
model myModel
J1: $Xo -> S1; k1*Xo - k2*S1;
J2: S1 -> S2; k3*S1 - k4*S2;
J3: S2 -> S3; k5*S2 - k6*S3;
J4: S3 -> S4; k7*S3 - k8*S4;
J5: S4 -> S5; k9*S4 - k10*S5;
J6: S5 -> ; k11*S5;
Xo = 1.0; S1 = 0.3; S2 = 0.1;
S3 = 0.2; S4 = 0.1; S5 = 0.2;
k1 = 3.92; k2 = 2.83; k3 = 0.8;
k4 = 0.24; k5 = 0.68; k6 = 0.35;
k7 = 0.82; k8 = 0.47; k9 = 0.37;
k10 = 0.22; k11 = 0.1;
end
′′′
phrasedml_str = ′′′
model1 = model ″myModel″
sim1 = simulate uniform(0, 30, 100)
task1 = run sim1 on model1
plot ″Figure 1″ time vs S1, S2, S3, S4, S5
′′′
inline_omex = ′\n′.join([antimony_str, phrasedml_str])

This setup can be directly executed in Python to check the output using executeInlineOmex, which will be identical to the plot shown in Figure 2.

te.executeInlineOmex(inline_omex)

Export this setup to a COMBINE archive using exportInlineOmex.

wDir = tempfile.mkdtemp(suffix=″_omex″)
te.exportInlineOmex(inline_omex, os.path.join(wDir, ′archive. omex′))

Now import and execute the COMBINE archive that was just exported to check that the output is the same as before.

te.executeCombineArchive(os.path.join(wDir, ′archive.omex′))

While it is possible to import COMBINE archives through Python functions, both Tellurium Spyder and Tellurium Notebooks provide simple GUI-based plug-ins to open a COMBINE archive as well. Detailed description on support for creating reproducible models in Tellurium will be discussed in a separate publication due to its broad scope.

Parameter Estimation

Parameter estimation is a common step in developing a model where the model is fitted to experimental data. Since Tellurium is based on Python, users can use the various optimization packages available in Python. More-over, Tellurium provides an environment where parameter estimation routines can be easily customized to deal with almost any fitting problem. To demonstrate Tellurium’s abilities in parameter estimation, we used a model of the central carbon metabolism of E. coli originally published by Chassagnole et al. [10] and later reformulated to be used as a part of benchmark suite for parameter estimation by Villaverde et al. [29]. The model is composed of 18 species and 48 reactions with 116 parameters to fit. Experimental data was supplied by the original authors, which consists of 110 time-course data points spread over 9 different metabolites. The reason why we choose this particular model is because 1) we have reference results to compare against, 2) the model is based on measured experimental data, and 3) the model presents a challenging parameter estimation problem where the reported ‘optimized’ results still does not fit well. Therefore, in this application, our goal will be to get a fit comparable to that obtained by Villaverde et al. [29].

The model presents a relatively large number of parameters to fit and many standard local optimization methods fail. Instead, a global optimizer is used to find a proper set of parameters. Here, we use the differential evolution optimizer supplied by the SciPy package. Figure 4B shows the result of parameter estimation on Tellurium, which is similar to the fit reported in the benchmark [29] and better than that of the original paper [10]. To compare the fit, we use cumulative normalized root-mean-squared error ($\sum \text{NRMSE}$), as was done by Villaverde et al. [29]. Root mean squared error measures the average of differences between observed and predicted values (error), and is given by Equation 1.

$$\text{RMSE = }\sqrt{\frac{1}{N}{\displaystyle \sum _{i=1}^N{\left(y_i-{\widehat{y}}_i\right)}^2}}$$ (1)

Here, N is the total number of the sample, y_i is the observed value, and ŷ_i is the predicted value. This value has been normalized against the observables by dividing by the difference between the maximum and minimum values of observables as shown in Equation 2.

$$\text{NRMSE =}\frac{\text{RMSE}}{\text{max(}{y}_i\text{)-min(}{y}_i\text{)}}$$ (2)

Our parameter optimization run results in $\sum \text{NRMSE}\approx 2.29$ which is similar to the value reported by Villaverde et al. ($\sum \text{NRMSE}\approx 2.49$) [29] and better than the original parameterization given by Chassagnole et al. ($\sum \text{NRMSE}\approx 3.61$) [10]. A plot of the residuals is provided as Supplementary Figure S1. Fitted parameters obtained from Tellurium are available in the Supplementary Materials.

A single run of parameter estimation using differential evolution took about 4.5 hours on a single core of Intel i7 4770 machine running at 3.4 GHz with 8GB RAM. Approximate standard errors on the fitted parameters can be obtained from the Hessian. For more accurate estimates it would be possible to use Monte Carlo or Profile Likelihood methods [26]. For the scope of this paper, we omit this step, but in the future, we will be supporting massively parallelized workloads through commercial cloud services that a user might be subscribed to.

Conclusion

With Tellurium, we provide the systems and synthetic biology community with an extensible Python-based modeling environment. We have endeavored to build a platform for collaboration by basing Tellurium on extensible and open architectures such as Spyder IDE and Jupyter Notebook. Our tools are available under Open Source Initiative (OSI)-approved open source licenses. As a result, our users have the freedom to apply further customizations to Tellurium. Pervasive support for systems biology standards enables models created by Tellurium to be stored, reused, and modified reliably by other software tools.

Availability

Installers for Tellurium Spyder are available for Microsoft Windows and Mac OS X. Jupyter Notebook versions of Tellurium (Tellurium Notebook) are available for Windows, Mac OS X, Debian and RedHat Linux distros. The Tellurium package is also available through PyPI. Binaries, documentation, and full source code are available at http://tellurium.analogmachine.org and https://github.com/sys-bio/tellurium. Tellurium is licensed under the Apache License Version 2.0. Scripts used for applications section are available in the Supplementary Materials.