Walkthrough

Notebook Walkthrough

If you have not already done so, download and install the Tellurium notebook front-end for your platform (Windows, Mac, and Linux supported).

Basics

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:

  • Press shift+Enter,
  • Click the play button at the upper right of the cell, or
  • Choose Cell -> Run All from the menu.

The output of running the cell will be shown beneath the cell.

Output of running a Python cell

Output of running a Python cell

Creating Cells

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, Import, and Merge. Choose 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.

Creating a new Markdown cell

Creating a new Markdown cell

Editing a Markdown cell

Editing a Markdown cell

SBML Cells

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 Import -> Import SBML....

Importing an SBML model

Importing an SBML model

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 BIOMD0000000012 to repressilator.

Changing the name of the model

Changing the name of the model

Now, run the cell. You should see confirmation that the model was correctly loaded and is available under the variable repressilator in Python.

Running the SBML cell

Running the SBML cell

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:

Simulating the SBML model

Simulating the SBML model

The 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.

Showing all auto-completions for the repressilator RoadRunner instance

Showing all auto-completions for the repressilator RoadRunner instance

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, choose Import -> 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:

Running the OMEX cell

Running the OMEX cell

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

To:

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:

Editing the OMEX cell

Editing the OMEX cell

You can re-export this cell to a COMBINE archive by clicking the diskette icon in the upper right:

Exporting the COMBINE archive

Exporting the COMBINE archive

Find/Replace in Notebook Cells

To search for text in a notebook cell, use ctrl+F. To search for whole-words only, use /\bmyword\b where myword is the word you want to search for.

Searching for whole words

Searching for whole words

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 ctrl+shift+R, enter /\bmyvar\b/ for the search field and newvar for the replace field. The result is that all instances of myvar are replaced, but not myvar2:

Search & replace demo with whole words

Search & replace demo with whole words

Example Notebooks

Tellurium comes with many example notebooks showing how to use its various features. To access these notebooks, use the File -> Open Example Notebook menu. Tellurium comes with five example notebooks:

Opening example notebooks

Opening example notebooks

The Quickstart notebook contains the `Quickstart <>`_ example from this documentation, using the SBML cells of the Tellurium notebook viewer.

Quickstart example notebook

Quickstart example notebook

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 File -> Export to Jupyter... from the menu. You will notice that the exported notebooks contain special cell magics such as %%crn and %%omex. To run these notebooks in Jupyter, install the temagics package in addition to tellurium using pip.


Notebook Troubleshooting

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.

Error message when kernel cannot be loaded

Error message when kernel cannot be loaded

Solution

In such a case, simply replace the kernel by choosing Language -> Python 3 from the menu.

Fix for kernel loading problem

Fix for kernel loading problem

Problem: Saving the Notebook Takes Forever

Solution

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.

Alternatively, choose Language -> Restart and Clear All Cells to save the notebook without output.

Reset and clear all cells

Reset and clear all cells


Further Reading


IDE Walkthrough

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

Learning Python