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¶
[39]:
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.
[40]:
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
¶
[41]:
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
[42]:
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.
[43]:
!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.
[44]:
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.
[45]:
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
.
[46]:
escher.list_available_maps()
[46]:
[{'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'}]
[47]:
escher.list_available_models()
[47]:
[{'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
.
[48]:
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
[49]:
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.
[50]:
builder = Builder()
[51]:
builder
And this time, try running some of the following cells and look at the response in the map above.
[52]:
# 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
[53]:
# 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
[54]:
# 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.
[55]:
!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.
[56]:
# Run FBA with the model and add the flux data to the map
solution = builder.model.optimize()
builder.reaction_data = solution.fluxes
[57]:
# Add some data for metabolites
builder.metabolite_data = solution.shadow_prices
[58]:
# Simplify the map by hiding some labels
builder.hide_secondary_metabolites = True
builder.hide_all_labels = True
[59]:
builder.reaction_scale = [
{ 'type': 'min', 'color': '#000000', 'size': 12 },
{ 'type': 'median', 'color': '#ffffff', 'size': 20 },
{ 'type': 'max', 'color': '#ff0000', 'size': 25 }
]
[60]:
builder.reaction_scale_preset = 'GaBuRd'
[61]:
# 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
]
[62]:
# 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:
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.
[63]:
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
[64]:
!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.
[65]:
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.
[66]:
builder.save_html('example_map.html')
[ ]: