This page was generated from docs/escher-python.ipynb. Executable online version:

4. Escher Python tutorial

The Escher Python package makes it easy to run and customize Escher visualizations from within a Jupyter Notebook or Jupyter lab. The Python package also works directly with COBRApy models. This tutorial introduces the main features. It is also a runnable notebook, which you can download here:

https://github.com/zakandrewking/escher/blob/master/docs/escher-python.ipynb

Once Escher and the appropriate extension are installed (next section), you should be able to run this notebook in Jupyter Notebook or Jupyter Lab.

If you don’t use Jupyter, you can also save standalone visualizations as HTML files using Escher Python. An example is included at the end of the tutorial.

4.1. Installation

You can install Escher Python with pip:

pip install escher

When you pip install escher, the Jupyter notebook extension should be installed automatically. If that doesn’t work, try:

# The notebook extenstion should install automatically. You can check by running:
jupyter nbextension list
# Make sure you have version >=5 of the `notebook` package
pip install "notebook>=5"
# To manually install the extension
jupyter nbextension install --py escher
jupyter nbextension enable --py escher
# depending on you environment, you might need the `--sysprefix` flag with those commands

To install the Jupyter lab extension, first install Escher with pip install escher then install the extension with these commands:

jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension install escher

If you have issues, you can leave a bug report on GitHub or ask for help on Gitter.

4.1.1. COBRApy

COBRApy is a Python package for constraint-based reconstruction and analysis of metabolic networks. It is an Escher dependency and should install automatically. If you want to learn more, go to: https://opencobra.github.io/cobrapy

4.2. Load an Escher map

4.2.1. To get started, we’ll import Escher and COBRApy

import escher
from escher import Builder
import cobra
from time import sleep

4.2.2. Global configuration

Escher currently offers on global configuration option. We will consider adding more in the future. This option turns off the warning message if you leave or refresh this page. The default setting is False to help you avoid losing work.

escher.rc['never_ask_before_quit'] = True

For most of this tutorial, all you need is the Builder class from escher.

4.2.3. The Builder

builder = Builder()

Builder is a Jupyter widget, so executing it in a cell will run the widget and embed an Escher map. You should see an empty Escher map in the next cell

builder

4.2.4. Finding models and maps

But the Builder isn’t very useful without some data!

In general, Escher is meant for building your own maps. Maps are generated with the content of genome-scale models, and you can find many models to explore on the BiGG Models database: http://bigg.ucsd.edu

Let’s download the red blood cell model iAB_RBC_283.

!wget -nc http://bigg.ucsd.edu/static/models/iAB_RBC_283.json

File ‘iAB_RBC_283.json’ already there; not retrieving.

We can add this model to the Escher Builder with the model_json option.

builder = Builder(
    model_json='iAB_RBC_283.json'
)

Now, in the following map, click “Edit > Add reaction mode” and click anywhere to start drawing reactions.

builder

Later, you can save this map by clicking “Map > Save map JSON”, and you can load JSON files in a Builder with the map_json option.

4.2.5. TIP: You can jump into full-screen mode by clicking the button on the map

In full-screen mode, keyboard shortcuts, mouse scrolling, and trackpad interactions are all activated.

To leave full-screen mode, press the escape key or click again.

4.2.6. Maps and models from the Escher website

Testing and getting started, Escher also provides a few default maps and models. You can see which ones are available with the following functions. To use a map or model, pass the name to the Builder options map_name and model_name.

escher.list_available_maps()

[{'organism': 'Saccharomyces cerevisiae',
  'map_name': 'iMM904.Central carbon metabolism'},
 {'organism': 'Homo sapiens',
  'map_name': 'RECON1.Inositol retinol metabolism'},
 {'organism': 'Homo sapiens', 'map_name': 'RECON1.Glycolysis TCA PPP'},
 {'organism': 'Homo sapiens', 'map_name': 'RECON1.Tryptophan metabolism'},
 {'organism': 'Homo sapiens', 'map_name': 'RECON1.Carbohydrate metabolism'},
 {'organism': 'Homo sapiens',
  'map_name': 'RECON1.Amino acid metabolism (partial)'},
 {'organism': 'Escherichia coli', 'map_name': 'iJO1366.Nucleotide metabolism'},
 {'organism': 'Escherichia coli',
  'map_name': 'iJO1366.Fatty acid biosynthesis (saturated)'},
 {'organism': 'Escherichia coli',
  'map_name': 'iJO1366.Nucleotide and histidine biosynthesis'},
 {'organism': 'Escherichia coli', 'map_name': 'e_coli_core.Core metabolism'},
 {'organism': 'Escherichia coli', 'map_name': 'iJO1366.Central metabolism'},
 {'organism': 'Escherichia coli',
  'map_name': 'iJO1366.Fatty acid beta-oxidation'}]

escher.list_available_models()

[{'organism': 'Saccharomyces cerevisiae', 'model_name': 'iMM904'},
 {'organism': 'Homo sapiens', 'model_name': 'RECON1'},
 {'organism': 'Escherichia coli', 'model_name': 'e_coli_core'},
 {'organism': 'Escherichia coli', 'model_name': 'iJO1366'}]

We can load these maps and models by specifying map_name and model_name.

builder = Builder(
    map_name='e_coli_core.Core metabolism',
    model_name='e_coli_core',
)

Downloading Map from https://escher.github.io/1-0-0/6/maps/Escherichia%20coli/e_coli_core.Core%20metabolism.json
Downloading Model from https://escher.github.io/1-0-0/6/models/Escherichia%20coli/e_coli_core.json

builder

4.2.7. Reactive options

The Escher Builder is a “reactive” widget, so it will update automatically when you change data and options. Let’s create another empty builder.

builder = Builder()

builder

And this time, try running some of the following cells and look at the response in the map above.

# Load an Escher map
builder.map_name = 'iJO1366.Central metabolism'

Downloading Map from https://escher.github.io/1-0-0/6/maps/Escherichia%20coli/iJO1366.Central%20metabolism.json

# Load a COBRA model
builder.model_name = 'e_coli_core'

Downloading Model from https://escher.github.io/1-0-0/6/models/Escherichia%20coli/e_coli_core.json

# Find any reactions that are in the map and not in the model, and turn them red
builder.highlight_missing = True

COBRA models are available directly from BiGG Models. Download a model from BiGG in the JSON format and read it with COBRApy.

!wget -nc http://bigg.ucsd.edu/static/models/iJO1366.json
builder.model = cobra.io.load_json_model('iJO1366.json')

File ‘iJO1366.json’ already there; not retrieving.

# Run FBA with the model and add the flux data to the map
solution = builder.model.optimize()
builder.reaction_data = solution.fluxes

# Add some data for metabolites
builder.metabolite_data = solution.shadow_prices

# Simplify the map by hiding some labels
builder.hide_secondary_metabolites = True
builder.hide_all_labels = True

builder.reaction_scale = [
    { 'type': 'min', 'color': '#000000', 'size': 12 },
    { 'type': 'median', 'color': '#ffffff', 'size': 20 },
    { 'type': 'max', 'color': '#ff0000', 'size': 25 }
]

builder.reaction_scale_preset = 'GaBuRd'

# Make all the arrows three times as thick
builder.reaction_scale = [
    {k: v * 3 if k == 'size' else v for k, v in x.items()}
    for x in builder.reaction_scale
]

# some other things to try:
# builder.scroll_behavior = 'zoom'
# builder.reaction_styles = ['size']

4.2.8. All options

The full list of options is provided in the Python API documentation:

https://escher.readthedocs.io/en/latest/python_api.html

For more-detailed descriptions of the Keyword Arguments, you can also refer to the JavaScript API docs:

https://escher.readthedocs.io/en/latest/javascript_api.html

4.3. Advanced: Make an animation

With reactive options, you can easily implement animations in an Escher map. Here’s a simple example where flux predictions are swept across and range to update the map of E. coli core metabolism.

builder = Builder(
    height=600,
    map_name=None,
    model_name='e_coli_core',
    map_json='https://escher.github.io/1-0-0/5/maps/Escherichia%20coli/e_coli_core.Core%20metabolism.json',
)
builder

Downloading Model from https://escher.github.io/1-0-0/6/models/Escherichia%20coli/e_coli_core.json

!wget -nc http://bigg.ucsd.edu/static/models/e_coli_core.json
model = cobra.io.load_json_model('e_coli_core.json')

File ‘e_coli_core.json’ already there; not retrieving.

reverse = False
step = 0.1
timestep = 0.1
duration = 15 # seconds
lim = [0, 0.5]
val = lim[-1]
for _ in range(int(duration / timestep)):
    model.reactions.EX_o2_e.lower_bound = -val
    solution = model.optimize()
    builder.reaction_data = solution.fluxes
    if val <= lim[0]:
        reverse = True
    if val >= lim[1]:
        reverse = False
    if reverse:
        val += step
    else:
        val -= step
    sleep(timestep)

cobra/util/solver.py:416 UserWarning: solver status is 'infeasible'

4.4. Saving maps as HTML

The Escher Builder can also be saved as a standalone HTML file, which you can view by opening in a browser. Just provide a filepath, and the map will be bundled along with all the current options.

builder.save_html('example_map.html')