If you have not already done so, download and install the Tellurium notebook front-end for your platform (Windows, Mac, and Linux supported).
The notebook environment allows you to mix Python code, narrative, and exchangeable standards for models and simulations. When you first open the notebook, you will have a single Python cell. You can type Python code into this cell. To run the code:
- Click the play button at the upper right of the cell, or
Run Allfrom the menu.
The output of running the cell will be shown beneath the cell.
You can add new cells by moving your cursor past the last cell in the notebook. You should see a menu with three options:
New to create a new cell. You will see four choices:
- New Python Cell
- New Markdown Cell (for creating narrative)
- New Model Cell (for SBML/Antimony models)
- New OMEX Cell (for COMBINE archives)
For now, select
New Markdown Cell. Markdown cells allow you to place formatted text and hyperlinks in your notebook. For a review of Markdown syntax, please see this reference.
Unlike vanilla Jupyter, Tellurium allows you embed a human-readable representation of SBML directly in your notebook. To begin, first download the SBML for the represillator circuit from BioModels. Then, in the Tellurium notebook viewer, move your cursor past the last cell in the notebook and select
Navigate to the
BIOMD0000000012.xml file that you downloaded and select it. A new cell will be created in the notebook with a human-readable representation of this model. The human-readable syntax is called Antimony, and you can find an extensive reference on the syntax here. For now, just change the name of the model from
Now, run the cell. You should see confirmation that the model was correctly loaded and is available under the variable
repressilator in Python.
After the SBML cell, create a Python cell with the following content:
repressilator.reset() # in case you run the cell again repressilator.simulate(0,1000,1000) # simulate from time 0 to 1000 with 1000 points repressilator.plot() # plot the simulation
After you run this cell, you should see the following simulation plot:
repressilator variable is actually an instance of the RoadRunner simulator. Please see the official documentation for libRoadRunner for an extensive list of methods and options that can be used with RoadRunner.
You can also use
ctrl+Space to open the auto-completion menu for a variable defined in a previous cell. This also goes for variables such as
repressilator defined in SBML cells.
COMBINE Archive Cells¶
Another name for COMBINE archives is the Open Modeling and EXchange format (OMEX), which shows up in various Tellurium menus and functions. COMBINE archives are containers for various community standards in systems biology. They can contain SBML, SED-ML, CellML, and NeuroML. Tellurium supports importing COMBINE archives containing SBML and SED-ML.
To begin, download this COMBINE archive example (originally from the SED-ML Web Tools). In the Tellurium notebook viewer, move the mouse past the last cell until the Cell Creator Bar appears and choose
Import COMBINE archive (OMEX)....
This archive contains an SBML model and a SED-ML simulation. The simulation has a forcing function (representing external input to the system) in the form of a pulse. After running this cell, you should see the following output:
As a demo of Tellurium’s COMBINE archive editing functionality, we can change the duration of the pulse. Change the following line:
task1 = repeat task0 for local.index in uniform(0, 10, 100), local.current = index -> piecewise(8, index < 1, 0.1, (index >= 4) && (index < 6), 8), model1.J0_v0 = current : current
task1 = repeat task0 for local.index in uniform(0, 10, 100), local.current = index -> piecewise(8, index < 1, 0.1, (index >= 4) && (index < 10), 8), model1.J0_v0 = current : current
In other words,
index < 6 was changed to
index < 10. Run the cell:
You can re-export this cell to a COMBINE archive by clicking the diskette icon in the upper right:
Find/Replace in Notebook Cells¶
To search for text in a notebook cell, use
ctrl+F. To search for whole-words only, use
myword is the word you want to search for.
To search and replace, use
ctrl+shift+R. For example, to replace
myvar but not
myvar2 (i.e. whole-word search & replace) in the code below, press
/\bmyvar\b/ for the search field and
newvar for the replace field. The result is that all instances of
myvar are replaced, but not
Tellurium comes with many example notebooks showing how to use its various features. To access these notebooks, use the
Open Example Notebook menu. Tellurium comes with five example notebooks:
The Quickstart notebook contains the Quickstart example from this documentation, using the SBML cells of the Tellurium notebook viewer.
Exporting to Jupyter¶
Tellurium notebooks can contain special cell types such as the SBML or OMEX cells described above. These notebooks cannot be properly read by Jupyter. However, you can export these notebooks to Jupyter by choosing
Export to Jupyter... from the menu. You will notice that the exported notebooks contain special cell magics such as
%%omex. To run these notebooks in Jupyter, install the
temagics package in addition to
tellurium using pip.
Using Other Jupyter Kernels / Languages¶
A built-in Python 3 kernel is provided with the notebook app. However, there are cases where this is not enough. Tellurium owes its existance in part to great free / open-source projects like nteract. We recommend anyone interest in a general-purpose notebook environment consider nteract instead.
Nevertheless, sometimes using a kernel other than the built-in Python 3 kernel is necessary. Starting with version 2.0.14, Tellurium supports automated discovery of other Jupyter kernels, such as different Python versions and distributions (e.g. Anaconda) and other languages (the Tellurium packages are not available in other languages). The following example shows how to use an R kernel with Tellurium.
- First, follow the installation instructions for the IRkernel (see also). These instructions use R 3.3.0. The following procedure for installing the IRkernel works for us:
install.packages('devtools') install.packages(c('repr', 'IRdisplay', 'evaluate', 'crayon', 'pbdZMQ', 'devtools', 'uuid', 'digest')) devtools::install_github('IRkernel/IRkernel')
- Make sure the IRkernel is registered:
- Start the Tellurium notebook app. Under the
Find Kernels.... A pop-up with a
Scanbutton should appear. Click the
Scanbutton. The results of the scan show all the kernels available to Tellurium. The built-in Python 3 and Node.js kernels are always available. Additional kernels appear based on installed Jupyter kernels. If you don’t see a Jupyter kernel you want here, make sure you have correctly installed the kernel (each his its own set of instructions). If the kernel still does not show up, make sure it is a true Jupyter kernel. Older IPython-based kernels (i.e. kernels which install under
~/.jupyter) cannot be discovered by Tellurium.
- Sometimes the path to a kernel’s executable can be displayed by hovering over the kernel’s name. The R kernel you installed should appear in the list. Click the accept button to cause the
Languagemenu to be updated with the new kernel choices.
- By selecting
R, you can cause the notebook to switch to the IRkernel. All code cells will be interpreted as R (SBML and OMEX cells will not work).
Problem: Cannot Load Kernel¶
The notebook viewer ships with a Python3 kernel, which causes problems when trying to open a notebook saved (e.g. by Jupyter) with Python2.
In such a case, simply replace the kernel by choosing
Python 3 from the menu.
Problem: Saving the Notebook Takes Forever¶
When highly detailed / numerous plots are present, Plotly is known to slow down notebook saving. In such cases, you can switch to matplotlib instead of Plotly by calling
import tellurium as te; te.setDefaultPlottingEngine('matplotlib') at the beginning of your notebook. When using matplotlib for plotting, the long save times do not occur.
Restart and Clear All Cells to save the notebook without output.
If you have not already done so, download and install the Tellurium IDE front-end for your platform (only for Windows, legacy versions supported Mac).
Additional Resources for Tellurium¶
- Suggest a new feature for Tellurium with UserVoice.
- Herbert Sauro’s modeling textbook, which uses Tellurium
- YouTube video tutorials (made prior to Tellurium notebook).