Escher

Escher is a web-based tool to build, view, share, and embed metabolic maps. The
easiest way to use Escher is to browse or build maps on the
Escher website.

Visit the documentation to get started with
Escher and explore the API.

Check out the
developer docs,
the Gitter chat room, and the
Development Roadmap for information
on Escher development. Feel free to submit bugs and feature requests as Issues,
or, better yet, Pull Requests.

Follow @zakandrewking for Escher updates.

You can help support Escher by citing our publication when you use Escher or
EscherConverter:

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

Escher was developed at SBRG. Funding was
provided by The National Science Foundation Graduate Research Fellowship
under Grant no. DGE-1144086, The European Commission as part of a Marie Curie
International Outgoing Fellowship within the EU 7th Framework Program for
Research and Technological Development (EU project AMBiCon, 332020),
and The Novo Nordisk Foundation
through The Center for Biosustainability
at the Technical University of Denmark (NNF10CC1016517)

Building and testing Escher

JavaScript

First, install dependencies with npm (or you can use
yarn):

``
brew install nvm pyenv
pyenv install 3.10.11
pyenv shell 3.10.11
python -m venv .venv
source .venv/bin/activate
nvm use
npm install
`

Escher uses webpack to manage the build process. To run typical build steps, just run:

`
npm run build
`

You can run a development server with:

`
npm run start


or for live updates when the source code changes:


npm run watch
`

To test the JavaScript files, run:

`
npm run test
`

Python

Escher has a Python package for generating Escher visualizations from within a
Python data anlaysis session. To learn more about using the features of the
Python package, check out the documentation:

https://escher.readthedocs.io/en/latest/escher-python.html

You can install it with pip:

`
pip install escher
`

Jupyter extensions

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

`bash


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, simply install Escher with pip install escher then
install the extension:

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

Python/Jupyter Development

For development of the Python package, first build the JavaScript package and
copy it over to the py directory with these commands in the Escher root:

`
npm install
npm run build
npm run copy
`

Then in the py directory, install the Python package:

`
cd py
pip install -r requirements.txt
`

To use the widgets within notebooks from jupyterlab, you also need to run the following from the escher root directory:
`bash
jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension install escher
`

For Python testing, run this in the py directory:

`
cd py
pytest
`

To develop the Jupyter notebook and Jupyter Lab extensions, you will need
install them with symlinks.

First, install the Python package for development as described above.

For the Jupyter notebooks, run:

`
cd py
jupyter nbextension install --py --symlink escher
jupyter nbextension enable --py escher
`

If you are using virtualenv or conda, you can add the --sys-prefix flag to
those commands to keep your environment isolated and reproducible.

When you make changes, you will need to yarn build && yarn copy and refresh
notebook browser tab.

For Jupyter Lab, run (in the root directory):

`
yarn watch # keep this running as a separate process
jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension link
jupyter lab --watch
`

If you don't see changes when you edit the code, try refreshing or restarting
jupyter lab --watch.

Docs

Build and run the docs::

`
cd docs
./build_docs
cd _build/html
python -m SimpleHTTPServer # python 2
python -m http.server # python 3
``