6. Developing with Escher¶
If you are interested in developing Escher or just want to try out the source code, this is the place to start. You might also want to check out the the Gitter chat room and the Development Roadmap.
6.1. Using the static JavaScript and CSS files¶
You can include the compiled Escher JavaScript and CSS files in any HTML
document. The only dependencies are d3.js, and optionally Twitter
Bootstrap if you are using the option menu='all'
.
The compiled files are available from unpkg:
https://unpkg.com/escher-vis/js/dist/escher.js
https://unpkg.com/escher-vis/js/dist/escher.min.js
https://unpkg.com/escher-vis/css/dist/builder.css
https://unpkg.com/escher-vis/css/dist/builder.min.css
Source maps are also hosted there:
https://unpkg.com/escher-vis/js/dist/escher.js.map
https://unpkg.com/escher-vis/js/dist/escher.min.js.map
https://unpkg.com/escher-vis/css/dist/builder.min.css.map
If you want a particular version of escher, add a version tag like this:
https://unpkg.com/escher-vis@1.4.0-beta.3/js/dist/escher.js
Or, if you use NPM, you can simply install escher-vis – the name escher was already taken:
npm install --save escher-vis
For an example of the boilerplate code that is required to begin developing with Escher, have a look at the escher-demo repository. For projects built with npm, use the escher-test repository as a guide.
6.2. Building and testing Escher¶
First, install dependencies with npm:
npm install
Escher uses grunt to manage the build process. To run typical build steps, just run:
npm run compile
To test the JavaScript files, run:
npm run test
For Python testing, run this in the py
directory:
python setup.py test
Build the static website:
python setup.py build_gh
Clear static website files:
python setup.py clean
Build and run the docs:
cd docs
make html
cd _build/html
python -m SimpleHTTPServer # python 2
python -m http.server # python 3
6.3. Generating and reading Escher and COBRA files¶
6.3.1. The Escher file format¶
Escher layouts are defined by JSON files that follow a specific schema, using
json schema. The latest schema for Escher JSON files is here. The Escher
schemas are versioned, with inspiration from SchemaVer. The escher.validate
module can be used to validate models against the schema.
The Escher layout schema is designed to be as simple as possible. For example, the core metabolism map of Escherichia coli is layed out like this:
[
{
"map_name": "E coli core.Core metabolism",
"map_id": "2938hoq32a1",
"map_description": "E. coli core metabolic network\nLast Modified Fri Dec 05 2014 16:39:44 GMT-0800 (PST)",
"homepage": "https://escher.github.io",
"schema": "https://escher.github.io/escher/jsonschema/1-0-0#"
},
{
"reactions": { ... },
"nodes": { ... },
"text_label": { ... },
"canvas": {
"x": 7.857062530517567,
"y": 314.36893920898433,
"width": 5894.515691375733,
"height": 4860.457037353515
}
},
]
The map_name
includes the model that was used to build this layout, followed by
a period and then a readable name for the map. The map_id
is a unique
identifier for this map. The map_description
describes the map and the last
time it was modified. Both the homepage
and the schema
entries must have
exactly these values for the Escher map to be valid.
In the next section, the reactions, nodes, labels, and canvas are all defined. For reactions, nodes, and text labels, each element has a key that is an arbitrary integer. As long as there are no repeated IDs (e.g. no 2 segments with the ID 517), then everything should work fine.
Read through the schema (here) for more detail on the format.
6.3.2. The COBRA file format¶
COBRA models are also saved as JSON files. This format has not been documented with a schema, but you can browse through the core metabolism model as a guide to generating valid COBRA models.
6.3.3. I still need help!¶
If you are interested in developing with Escher and you need more information than what is provided in the documentation, please contact Zachary King (zaking-AT-ucsd-DOT-edu).