Escher (modernized fork)

This is a maintained fork of Escher, originally created by Zachary A. King and collaborators at UC San Diego. The original project has been unmaintained since ~2019.

Several open issues in the upstream repo motivated this fork:

• Installation broken on Python 3.12+ — narrow dependency pins (ipywidgets<8, Jinja2<3, etc.) prevent installation in modern environments (zakandrewking/escher#389)
• Jupyter widget incompatible with JupyterLab — the ipywidgets/RequireJS nbextension mechanism doesn't work in JupyterLab 3+, VS Code, or other current notebook frontends (zakandrewking/escher#397)
• Node merge broken — dragging metabolite nodes to merge them silently fails, making it impossible to build clean maps (zakandrewking/escher#396, opencobra/escher#22)

This fork fixes all of the above and modernizes the toolchain so Escher remains usable for metabolic map visualization.

What changed

Area	Before	After
Python packaging	setup.py + setuptools	pyproject.toml + uv
JS build	Webpack 4	Vite
JS tests	mochapack	Vitest
Jupyter widget	ipywidgets (required extension install)	anywidget (zero-install)
Drag-drop node merge	Broken (D3 pointer capture issue)	Fixed via document.elementFromPoint

Citation

If you use Escher in published work, please cite the original paper:

Zachary A. King, Andreas Dräger, Ali Ebrahim, Nikolaus Sonnenschein, Nathan E. Lewis, and Bernhard O. Palsson (2015) Escher: A web application for building, sharing, and embedding data-rich visualizations of biological pathways, PLOS Computational Biology 11(8): e1004321. doi:10.1371/journal.pcbi.1004321

Installation

pip install git+https://github.com/cplong90/escher.git#subdirectory=py

No Jupyter extensions to install. Escher uses anywidget and works out of the box in JupyterLab 4, Jupyter Notebook, VS Code, Cursor, Google Colab, and Marimo.

Basic usage

import escher

# Display a map in a notebook
builder = escher.Builder(map_name='e_coli_core')
builder  # renders the interactive map

# Load flux data
builder.reaction_data = {'PFK': 1.5, 'PYK': 0.8}

# React to map clicks in Python
builder.observe(lambda change: print(change['new']), names='selected_reaction')

To overlay flux from a COBRApy model:

import cobra
import escher

model = cobra.io.load_model('textbook')
solution = model.optimize()

builder = escher.Builder(
    map_name='e_coli_core',
    model=model,
    reaction_data=solution.fluxes.to_dict(),
)
builder

Building and testing from source

Requirements

• Node.js 18+
• Yarn (classic / v1)
• Python 3.8+
• uv

JavaScript

yarn install          # install dependencies
yarn build            # produce dist/escher.js and dist/escher-widget.js
yarn test             # run JS tests
yarn copy             # copy build artifacts to py/escher/static/

Escher uses Vite to manage the build process. For live development:

yarn watch            # rebuild on source changes
yarn start            # start the Vite dev server

Python

The JS build artifacts must be copied to py/escher/static/ before installing the Python package from source. If you just ran yarn copy above, you're ready:

cd py
uv sync --extra dev   # install package and dev dependencies
uv run pytest         # run Python tests

Full clean build

From the repo root:

yarn install && yarn build && yarn copy
cd py && uv sync --extra dev && uv run pytest

License

MIT — see LICENSE. Original copyright © 2015 The Regents of the University of California.