Welcome to the documentation for Escher¶

Getting started¶

The launch page¶

When you open the Escher website, you will see a launch page that looks like this:

The options on the launch page are:

• Filter by organism: Choose an organism to filter the Maps and Models.

• Map: Choose a pre-built map, or start from scratch with an empty builder by choosing None. In parentheses next to the map name, you will see the name of the model that was used to build this map.

• Model: (Optional) If you choose a COBRA model to load, then you can add new reactions to the pathway map. You can also load your own model later, after you launch the tool. For an explanation of maps, models, and COBRA, see Escher, COBRA, and COBRApy.

• Tool:

  • The Viewer allows you to pan and zoom the map, and to visualize data for reactions, genes, and metabolites.
  • The Builder, in addition to the Viewer features, allows you to add reactions, move and rotate existing reactions, add text annotations, and adjust the map canvas.

• Options:

  • Scroll to zoom (instead of scroll to pan): Determines the effect of using the mouse’s scroll wheel over the map.
  • Never ask before reloading: If this is checked, then you will not be warned before leaving the page, even if you have unsaved changes.
  • Responsive pan and zoom: If this is checked, then the panning and zooming will take place without drawing the map, in order to make panning and zooming more responsive. This feature works best in the latest versions of Chrome, Firefox and Internet Explorer. In Safari it is better to leave this off.

Choose Load map to open the Escher viewer or builder in a new tab, and prepare to be delighted by your very own pathway map.

The menu bar¶

Once you have loaded an Escher map, you will see a menu bar along the top of the screen. Click the question mark to bring up the Escher documentation:

Loading and saving maps¶

Using the map menu, you can load and save maps at any time:

Click Save map JSON to save the Escher map as a JSON file, which is the standard file representing an Escher map. NOTE: The JSON file does NOT save any datasets you have loaded. This may be changed in a future version of Escher.

Later, you can can load a JSON file to view and edit a map by clicking Load map JSON.

Click Export as SVG to generate a SVG file for editing in tools like Adobe Illustrator and Inkscape. This is the best way to generate figures for presentations and publications. Unlike a JSON file, a SVG file maintains the data visualizations on the Escher map. However, you cannot load SVG files into Escher after you generate them.

Click Clear Map to empty the whole map, leaving a blank canvas. NOTE: You cannot undo Clear Map.

Loading models¶

Use the model menu to manage the COBRA model loaded in Escher:

Choose Load COBRA model JSON to open a COBRA model. Read more about COBRA models in Escher, COBRA, and COBRApy. Once you have COBRApy v0.3.0 or later installed, then you can generate a JSON model by following this example code.

Once you have loaded a COBRA model, there may be inconsistencies between the content in the map and the model (e.g. reaction IDs, descriptive names and gene reaction rules). You click Update names and gene reaction rules using model to find matching reactions and metabolites between the map and the model (based on their IDs) and then apply the names and gene reaction rules from the model to the map. The reactions that do not match will be highlighted in red. (This can be turned off again in the settings menu by deselecting Highlight reactions not in model.) More advice on building maps is available in Building and contributing maps.

Click Clear Model to clear the current model.

Loading reaction, gene, and metabolite data¶

Datasets can be loaded as CSV files or JSON files, using the Data Menu.

In Escher, reaction and gene datasets are visualized by changing the color, thickness, and labels of reaction arrows. Metabolite datasets are visualized by changing the color, size, and labels of metabolite circles. The specific visual styles can be modified in the Settings menu. When data is not present for a specific reaction, gene, or metabolite, then the text label will say ‘nd’ which means ‘no data.’

The structure of a CSV file¶

CSV files should have 1 header row, 1 ID column, and either 1 or 2 columns for data values. The ID column can contain BiGG IDs or descriptive names for the reactions, metabolites, or genes in the dataset. Here is an example with a single data value columns:

ID,time 0sec
glc__D_c,5.4
g6p__D_c,2.3

Which might look like this is Excel:

ID	time 0sec
glc__D_c	5.4
g6p_c	2.3

If two datasets are provided, then the Escher map will display the difference between the datasets. In the Settings menu, the Comparison setting allows you to choose between comparison functions (Fold Change, Log2(Fold Change), and Difference). With two datasets, the CSV file looks like this:

ID	time 0sec	time 5s
glc__D_c	5.4	10.2
g6p_c	2.3	8.1

Data can also be loaded from a JSON file. This Python code snippet provides an example of generating the proper format for single reaction data values and for reaction data comparisons:

import json

# save a single flux vector as JSON
flux_dictionary = {'glc__D_c': 5.4, 'g6p_c': 2.3}
with open('out.json', 'w') as f:
    json.dump(flux_dictionary, f)

# save a flux comparison as JSON
flux_comp = [{'glc__D_c': 5.4, 'g6p_c': 2.3}, {'glc__D_c': 10.2, 'g6p_c': 8.1}]
with open('out_comp.json', 'w') as f:
    json.dump(flux_comp, f)

Gene data and gene reaction rules¶

Escher uses gene reaction rules to connect gene data to the reactions on a metabolic pathway. You can see these gene reaction rules on the map by selecting Show gene reaction rules in the Settings menu.

Gene reaction rules show the genes whose gene products are required to catalyze a reaction. Gene are connected using AND and OR rules. AND rules are used when two genes are required for enzymatic activity, e.g. they are members of a protein complex. OR rules are used when either gene can catalyze the enzymatic activity, e.g. they are isozymes.

With OR rules, Escher will take the sum of the data values for each gene. With AND rules, Escher will either take the mean (the default) or the minimum of the components. The AND behavior (mean vs. minimum) is defined in the Settings menu.

Editing and building¶

The Edit menu gives you access to function for editing the map:

Escher has five major modes, and you can switch between those modes using the buttons in the Edit menu, or using the buttons in the button bar on the left of the screen.

1. Pan mode: Drag the canvas to pan the map. You can also use the mouse scroll wheel or trackpad scroll function (drag with 2 fingers) to pan the map (or to zoom if you selected Scroll to zoom in the settings).
2. Select mode: Select nodes by clicking on them. Shift-click to select multiple nodes, or drag across the canvas to select multiple nodes using the selection brush.
3. Add reaction mode: If you have loaded a Model, then click on the canvas to see a list of reactions that you can draw on the map. Click on a node to see reactions that connect to that node. In the input box, you can search by reaction ID, metabolite ID, or gene ID (locus tag).
4. Rotate model: Before entering rotate mode, be sure to select one or more nodes in select mode. Then, after entering rotate mode, drag anywhere on the canvas to rotate the selection. You can also drag the red crosshairs to change the center of the rotation.
5. Text mode: Use text mode to add text annotations to the map. Click on the canvas to add a new text annotation, or click an existing annotation to edit it. When you are finished, click Enter or Escape to save the changes.

In addition to the editing modes, the Edit menu gives you access to the following commands:

• Delete: Delete the currently selected node(s).

• Undo: Undo the last action. NOTE: Certain actions, such as editing the canvas, cannot be undone in the current version of Escher.

• Redo: Redo the last action that was undone.

• Toggle primary/secondary node: In Escher, each metabolite node is either a primary node or a secondary node. Primary nodes are larger, and secondary nodes can be hidden in the Settings menu. Use this command to toggle the currently selected node(s) between primary and secondary.

• Rotate reactant locations: When you draw a new reaction in Escher, this command will rotate the new reactants so that a new reactant is primary and centered. This command is extremely useful when you are drawing a long pathway and you want to quickly switch which metabolite to “follow”, e.g. make sure you are following the carbon-containing metabolites.

  If you are confused, then try drawing a new pathway and hitting the “c” key to see the reactants rotate.

• Select all: Select all nodes.

• Select none: Unselect all nodes.

• Invert selection: Select all the nodes that are currently unselected. This feature is very useful when you want to keep just one part of the map. Simply drag to select the part you want to keep, call the Invert selection command, then call the Delete command.

View options¶

• Zoom in: Zoom in to the map.
• Zoom out: Zoom out of the map.
• Zoom to nodes: Zoom to see all the nodes on the map.
• Zoom to canvas: Zoom to see the entire canvas.
• Find: Search for a reaction, metabolite, or gene on the map.
• Show control points: Show the control points; you can drag these red and blue circle to adjust the shapes of the reactions curves.
• Settings: Open the Settings menu.

The button bar¶

The button bar give you quick access to many of the common Escher functions:

Settings¶

View and build options¶

• Identifiers: Choose whether to show BiGG IDs or descriptive names for reactions, metabolites, and genes.
• Hide secondary metabolites: This will simplify the map by hiding all secondary metabolites and the paths connected to them.
• Show gene reaction rules: Show the gene reaction rules below the reaction labels, even gene data is not loaded.
• Hide reaction, gene, and metabolite labels: Another option to visually simplify the map, this will hide all labels that are not text annotations.
• Allow duplicate reactions: By default, duplicate reactions are hidden in the add reaction dropdown menu. However, you can turn this option on to show the duplicate reactions.
• Highlight reactions not in model: Highlight in red any reactions that are on the map but are not in the model. This is useful when you are adapting a map from one model for use with another model

Reaction data settings¶

When reaction or gene data is loaded, this section can be used to change visual settings for reactions.

The color bar has individual control points, and you can drag the control points (execpt min and max) left and right to change their values. Alternatively, you can use the dropdown menu (next to the word median in the figure above), to attach a control point to a statistical measure (mean, median, first quartile (Q1), or third quartile (Q3)). This lets you choose a color scale that will adapt to your dataset.

For each control point, you can choose a color by entering a CSS-style color (e.g. red, #ff0000, rgba(20, 20, 255, 0.5), and you can choose a size that will scale the thickness of reactions.

There are also color and size options for reactions that do not have any data value.

Finally, there are a few on/off settings for the loaded reaction or gene dataset:

• Options: These determine how to visualize the datasets. Check Absolute value to color and size reactions by the absolute value of each data value. The Size, Color, and Text options can be unselected to turn off sizing, coloring, and data values in reaction labels individually.
• Comparison: Determines the comparison algorithm to use when two datasets are loaded.
• Method for evaluating AND: Determines the method that will be used to reconcile AND statements in gene reaction rules when there is gene data loaded. See Gene data and gene reaction rules for more details.

Metabolite data settings¶

The data settings for metabolite data are analagous to those for reaction data. The only difference is that size now refers to the size of the metabolite circles.

Escher, COBRA, and COBRApy¶

Escher can be used as an independent application, but it draws heavily on the information in COBRA models. A COBRA model is a collection of all the reactions, metabolites, and genes known to exist in an organism. (In the literature, these are generally called genome-scale models (GEMs), but we refer to them as COBRA models here to emphasize that Escher interoperates with models that are exported from COBRApy.)

By loading a COBRA model into the Escher interface, you have access to every reaction and metabolite in that model. You also have the gene reaction rules for the reactions in the network, which allow you to connect gene data to reactions and metabolites.

COBRApy is a software package for COBRA modeling written in Python. The Escher Python package uses COBRApy package for reading and writing COBRA models.

import json

with open('map.json', 'r') as f:
    map_object = json.load(f)

print map_object[0]
print map_object[1]['reactions'].values()[0]

Run Escher locally and in IPython¶

To run Escher on a local computer or to use Escher in Python/IPython, first install it. The Python package for Escher can be installed using pip:

pip install escher

Depending on your installation of Python, you may need sudo:

sudo pip install escher

Alternatively, one can download the source files and install the package directly:

python setup.py install

python -m escher.server

python -m escher.server --port=8005

Convert maps¶

Any Escher maps built with pre-release versions of Escher will not load right away in the stable v1.0 release. To convert pre-release maps to the new format, follow these steps:

1. Install Escher:

   pip install escher
   

2. Find a COBRA model for your maps. This COBRA model will be used to update the content of the map in order to support all the new Escher features. You can use a COBRA model encoded as SBML or JSON (generated with COBRApy v0.3.0b4 or later). The COBRA models currently available on the Escher website can be downloaded here:

https://github.com/escher/escher.github.io/tree/master/1-0-0/models

For a refresher on the distinction between Escher maps, COBRA models, and their file types (SBML, JSON, SBML Layout), see Escher, COBRA, and COBRApy.

3. Run the convert_map script to convert your existing Escher map (my_old_map.json) to the new format, using a COBRA model (model_file.json or model_file.xml in these examples):

   # With a JSON file model
   python -m escher.convert_map my_old_map.json path/to/model_file.json
   
   # With an SBML model
   python -m escher.convert_map my_old_map.json path/to/model_file.xml
   

Those commands will generate a new map called my_old_map_converted.json that will load in Escher v1.0 and later.

Building and contributing maps¶

We are excited to collect pathway maps for every organism with a well characterized metabolic network. This section describes the process of building a new map, either from scratch or using a COBRA model with BiGG IDs.

1-0-0/maps/Saccharomyces cerevisiae/

iMM904.Amino acid biosynthesis.json

1-0-0/maps/Saccharomyces cerevisiae/iMM904.Amino acid biosynthesis.json
1-0-0/models/Saccharomyces cerevisiae/iMM904.json

Developing with Escher¶

python setup.py buildjs

python setup.py test

python setup.py buildgh

python setup.py clean

[
    {
        "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
        }
    },
]

EscherConverter¶

EscherConverter is a standalone program that reads files created with the graphical network editor Escher and converts them to files in community standard formats.

Download EscherConverter 0.5 (13.7 MB).

Using EscherConverter¶

Escher uses a JSON file format to represent its networks. This format has been developed because of its very small file size and its compatibility to online programs that are written in JavaScript. In particular, JSON is a JavaScript Object Notation, or in other words, a JSON file directly represents components of JavaScript programs. This makes parsing very simple and allows direct use of those files in web-based programs.

However, in systems biology, specific file formats have been developed with the aim to be easily exchangeable between software implemented in diverse programming languages.

To this end, these formats support semantically clear annotations and are maintained by a large community of scientists. EscherConverter supports export to two particularly important XML-based community file formats SBML with layout extension and SBGN-ML.

While SBML has been mainly developed for dynamic simulation of biological networks, it is nowadays also usable for diverse other purposes. Its layout extension facilitates the encoding the display of biological networks.

SBGN-ML has been directly developed as a language for the display of biological pathway maps of diverse kinds. It stores the position and connection of entities, similar to what is shown in Escher networks.

EscherConverter takes Escher’s JSON files as input and generates equivalent SBML Level 3 Version 1 files with layout extension or SBGN-ML files.

In order to ensure that the conversion is correct, EscherConverter provides its own display that gives users a preview of how the export data format will be rendered by other tools. In this preview display, you can zoom in and out, move arcs and node positions. However, it is important to know that none of the changes made in this preview are stored in the export file.

Download and Installation¶

You can obtain local copy of EscherConverter by clicking here.

As a Java™ application, no specific installation is required for EscherConverter.

However, make sure you have a recent Java™ Runtime Environment (JRE) installed on your computer (at least JRE 8). You can obtain Java™ from the Oracle website. There you can also find installation instructions for your respective operating system.

Once Java™ has been installed, you can simply place the EscherConverter JAR file somewhere on your local computer, for instance in the folder

• /Applications/ if you are working under Mac OS
• /opt/ for Linux computers
• C:\Program Files\ if you are using Windows

Launching the program¶

You can launch EscherConverter simply by double-clicking on the application JAR file. This will open a following graphical user interface as described in the following figures.

Figure 1 | The graphical user interface of EscherConverter.

• Preferences: opens a settings dialog (see next screenshot).
• Open: displays a file chooser to select an input file in JSON format.
• Save: export the map that is displayed in the current tab to SBML or SBGN-ML.
• Discard: closes the current tab without saving.
• Help: opens the online help that displays all command-line options.
• License: displays the license under which this software is distributed.
• About: shows information about the authors of this software.
• Main: the main panel of the software, in which converted Escher maps will be displayed, organized in tabs.
• Status: the status bar shows information and logging messages during the conversion.

Figure 2 | The preferences dialog. All settings in this dialog are also available through EscherConverter’s command-line interface.

Layout section: several properties that are required in SBML and SBGN-ML are not explicitly specified in Escher’s JSON format and therefore need to be adjusted by the user. These are the size of the drawing canvas, the default box size for text labels, the size of primary and secondary nodes. In contrast to SBGN-ML and Escher’s JSON format, the SBML layout extension supports three-dimensional displays. When selecting this export file format, it is therefore necessary to also define the z-coordinate and the depth of all objects.

Components and naming section: Most settings in this section are specific for the SBML layout extension and are only active if this output format is selected. These are names and identifiers of the layout component and the, in case of SBML, mandatory default compartment (a compartment without physical meaning, a reaction space in which all metabolites are located). EscherConverter can infer compartment bounds from metabolites, but this is an experimental feature. Just try it and see how the preview changes.

Figure 3 | A layout preview.

The birds-eye view and the navigation component on the left help you navigate through the network display. This graph shows you how the converted pathway map will be rendered by software that supports SBGN-ML or the SBML layout extension. This preview can be modified by moving arcs or nodes, however, none of those changes are stored when exporting the file. In this current version, EscherConver only exports layouts as given in the original JSON file.

Included third-party software¶

EscherConverter includes several third-party libraries, which we here list and acknowledge:

• ArgParser
• JSBML
• libSBGN
• Pixel-Mixer icons
• yFiles

bash$ java -jar -Xms8G -Xmx8G -Duser.language=en ./EscherConverter-0.5.jar [options]

C:\> javaw -jar -Xms8G -Xmx8G -Duser.language=en EscherConverter-0.5.jar [options]

--input=<File>

--output=<File>

--canvas-default-height=<Double>

--canvas-default-width=<Double>

--label-height=<Double>

--label-width=<Double>

--node-depth=<Double>

--node-label-height=<Double>

--primary-node-height=<Double>

--primary-node-width=<Double>

--reaction-label-height=<Double>

--reaction-node-ratio=<Double>

--secondary-node-ratio=<Double>

--z=<Double>

--format=<OutputFormat>

--layout-id=<String>

--layout-name=<String>

--compartment-id=<String>

--compartment-name=<String>

--infer-compartment-bounds

--gui

--log-level=<String>

--log-file=<File>

JavaScript API¶

class escher.Builder(map_data, model_data, embedded_css, options)¶

A Builder object contains all the UI and logic to generate a map builder or viewer.

Arguments:

map_data (object) – The data for a map, to be passed to escher.Map.from_data(). If null, then an empty Builder is initialized model_data (object) – The data for a cobra model, to be passed to escher.CobraModel(). Can be null. embedded_css (string) – The stylesheet for the SVG elements in the Escher map. selection (object) – (Optional, Default: In the body element) The d3 selection of an element to place the Builder into. The selection cannot be inside an SVG element. options (object) – (Optional) An object defining any of the following options: options.menu¶ (Default: ‘all’) The type of menu that will be displayed. Can be ‘all’ for the full menu or ‘zoom’ for just zoom buttons. The ‘all’ option requires the full set of Escher dependencies (D3.js, JQuery, and Bootstrap), while the ‘zoom’ option requires only D3.js. For more details, see Developing with Escher. options.scroll_behavior¶ (Default: ‘pan’) This option determines the effect that the scroll wheel will have on an Escher map. Can be ‘pan’ to pan the map or ‘zoom’ to zoom the map when the user moves the scroll wheel. options.use_3d_transform¶ (Default: false) If true, then use CSS3 3D transforms to speed up panning and zooming. This feature will only work on browsers that support the 3D transforms. It works best in the latest versions of Chrome, Firefox and Internet Explorer. Safari works better with this turned off. options.enable_editing¶ (Default: true) If true then display the map editing functions. If false, then hide them and only allow the user to view the map. option.enable_keys¶ (Default: true) If true then enable keyboard shortcuts. options.enable_search¶ (Default: true) If true, then enable indexing of the map for search. Use false to disable searching and potentially improve the map performance. options.fill_screen¶ (Default: false) Use true to fill the screen when an Escher Builder is placed in a top-level container (e.g. a div in the body element). Map, model, and styles options.starting_reaction¶ (Default: null) The ID (as a string) of a reaction to draw when the Builder loads. options.never_ask_before_quit¶ (Default: false) If false, then display a warning before the user closes an Escher map. If true, then never display the warning. This options is only respected if options.enable_editing == true. If enable_editing is false, then the warnings are not displayed. options.unique_map_id¶ (Default: null) A unique ID that will be used to UI elements don’t interfere when multiple maps are in the same HTML document. options.primary_metabolite_radius¶ (Default: 15) The radius of primary metabolites, in px. options.secondary_metabolite_radius¶ (Default: 10) The radius of secondary metabolites, in px. options.marker_radius¶ (Default: 5) The radius of marker nodes, in px. options.gene_font_size¶ (Default: 18) The font size of the gene reaction rules, in px. options.hide_secondary_metabolites¶ (Default: false) If true, then secondary nodes and segments are hidden. This is convenient for generating simplified map figures. options.show_gene_reaction_rules¶ (Default: false) If true, then show the gene reaction rules, even without gene data. options.hide_all_labels¶ (Default: false) If checked, hide all reaction, gene, and metabolite labels Applied data options.reaction_data¶ (Default: null) An object with reaction ids for keys and reaction data points for values. options.reaction_styles¶ (Default: [‘color’, ‘size’, ‘text’]) An array of style types. The array can contain any of the following: ‘color’, ‘size’, ‘text’, ‘abs’. The ‘color’ style means that the reactions will be colored according to the loaded dataset. The ‘size’ style means that the reactions will be sized according to the loaded dataset. The ‘text’ style means that the data values will be displayed in the reaction labels. The ‘abs’ style means the the absolute values of reaction values will be used for data visualization. options.reaction_compare_style¶ (Default: ‘diff’) How to compare to datasets. Can be either ‘fold, ‘log2_fold’, or ‘diff’. options.reaction_scale¶ (Default: [{ type: ‘min’, color: ‘#c8c8c8’, size: 12 }, { type: ‘median’, color: ‘#9696ff’, size: 20 }, { type: ‘max’, color: ‘#ff0000’, size: 25 }]) options.reaction_no_data_color¶ (Default: ‘#dcdcdc’) The color of reactions with no data value. options.reaction_no_data_size¶ (Default: 8) The size of reactions with no data value. options.gene_data¶ (Default: null) An object with Gene ids for keys and gene data points for values. options.and_method_in_gene_reaction_rule¶ (Default: mean) When evaluating a gene reaction rule, use this function to evaluate AND rules. Can be ‘mean’ or ‘min’. options.metabolite_data¶ (Default: null) An object with metabolite ids for keys and metabolite data points for values. options.metabolite_styles¶ (Default: [‘color’, ‘size’, ‘text’]) An array of style types. The array can contain any of the following: ‘color’, ‘size’, ‘text’, ‘abs’. The ‘color’ style means that the metabolites will be colored according to the loaded dataset. The ‘size’ style means that the metabolites will be sized according to the loaded dataset. The ‘text’ style means that the data values will be displayed in the metabolite labels. The ‘abs’ style means the the absolute values of metabolite values will be used for data visualization. options.metabolite_compare_style¶ (Default: ‘diff’) How to compare to datasets. Can be either ‘fold’, ‘log2_fold’ or ‘diff’. options.metabolite_scale¶ (Default: [ { type: ‘min’, color: ‘#fffaf0’, size: 20 }, { type: ‘median’, color: ‘#f1c470’, size: 30 }, { type: ‘max’, color: ‘#800000’, size: 40 } ]) options.metabolite_no_data_color¶ (Default: ‘#ffffff’) The color of metabolites with no data value. options.metabolite_no_data_size¶ (Default: 10) The size of metabolites with no data value. View and build options options.identifiers_on_map¶ (Default: ‘bigg_id’) The identifiers that will be displayed in reaction, metabolite, and gene labels. Can be ‘bigg_id’ or ‘name’. options.highlight_missing¶ (Default: false) If true, then highlight in red reactions that are not in the loaded COBRA model. options.allow_building_duplicate_reactions¶ (Default: true) If true, then building duplicate reactions is allowed. If false, then duplicate reactions are hidden in Add reaction mode. Callbacks options.first_load_callback¶ A function to run after loading the Builder.

load_map(map_data[, should_update_data])¶

Load a map for the loaded data. Also reloads most of the Builder content.

Arguments:	map_data – The data for a map. should_update_data (Boolean) – (Default: true) Whether data should be applied to the map.

load_model(model_data[, should_update_data])¶

Load the cobra model from model data.

Arguments:	model_data – The data for a Cobra model. (Parsing in done by escher.CobraModel). should_update_data (Boolean) – (Default: true) Whether data should be applied to the model.

view_mode()¶

Enter view mode.

build_mode()¶

Enter build mode.

brush_mode()¶

Enter brush mode.

zoom_mode()¶

Enter zoom mode.

rotate_mode()¶

Enter rotate mode.

text_mode()¶

Enter text mode.

set_reaction_data(data)¶

Arguments:	data (array) – An array of 1 or 2 objects, where each object has keys that are reaction ID’s and values that are data points (numbers).

set_metabolite_data(data)¶

Arguments:	data (array) – An array of 1 or 2 objects, where each object has keys that are metabolite ID’s and values that are data points (numbers).

set_gene_data(data, clear_gene_reaction_rules)¶

Arguments:	data (array) – An array of 1 or 2 objects, where each object has keys that are gene ID’s and values that are data points (numbers). clear_gene_reaction_rules (Boolean) – (Optional, Default: false) In addition to setting the data, also turn of the gene_reaction_rules.

Python API¶

class escher.Builder(map_name=None, map_json=None, model=None, model_name=None, model_json=None, embedded_css=None, reaction_data=None, metabolite_data=None, gene_data=None, local_host=None, id=None, safe=False, **kwargs)¶

A metabolic map that can be viewed, edited, and used to visualize data.

This map will also show metabolic fluxes passed in during consruction. It can be viewed as a standalone html inside a browswer. Alternately, the respresentation inside an IPython notebook will also display the map.

Maps are stored in json files and are stored in a cache directory. Maps which are not found will be downloaded from a map repository if found.

Parameters:

map_name – A string specifying a map to be downloaded from the Escher web server, or loaded from the cache. map_json – A JSON string, or a file path to a JSON file, or a URL specifying a JSON file to be downloaded. model – A Cobra model. model_name – A string specifying a model to be downloaded from the Escher web server, or loaded from the cache. model_json – A JSON string, or a file path to a JSON file, or a URL specifying a JSON file to be downloaded. embedded_css – The CSS (as a string) to be embedded with the Escher SVG. reaction_data – A dictionary with keys that correspond to reaction ids and values that will be mapped to reaction arrows and labels. metabolite_data – A dictionary with keys that correspond to metabolite ids and values that will be mapped to metabolite nodes and labels. gene_data – A dictionary with keys that correspond to gene ids and values that will be mapped to corresponding reactions. local_host – A hostname that will be used for any local files in dev mode. id – Specify an id to make the javascript data definitions unique. A random id is chosen by default. safe – If True, then loading files from the filesytem is not allowed. This is to ensure the safety of using Builder with a web server.

Keyword Arguments

These are defined in the Javascript API:

• identifiers_on_map
• show_gene_reaction_rules
• unique_map_id
• primary_metabolite_radius
• secondary_metabolite_radius
• marker_radius
• hide_secondary_metabolites
• reaction_styles
• reaction_compare_style
• reaction_scale
• reaction_no_data_color
• reaction_no_data_size
• and_method_in_gene_reaction_rule
• metabolite_styles
• metabolite_compare_style
• metabolite_scale
• metabolite_no_data_color
• metabolite_no_data_size
• highlight_missing
• allow_building_duplicate_reactions

All keyword arguments can also be set on an existing Builder object using setter functions, e.g.:

my_builder.set_reaction_styles(new_styles)

display_in_browser(ip=u'127.0.0.1', port=7655, n_retries=50, js_source=u'web', menu=u'all', scroll_behavior=u'pan', enable_editing=True, enable_keys=True, minified_js=True, never_ask_before_quit=False)¶

Launch a web browser to view the map.

Parameters:

ip – The IP address to serve the map on. port – The port to serve the map on. If specified the port is occupied, then a random free port will be used. n_retries (int) – The number of times the server will try to find a port before quitting. js_source (string) – Can be one of the following: web (Default) - Use JavaScript files from escher.github.io. local - Use compiled JavaScript files in the local Escher installation. Works offline. dev - Use the local, uncompiled development files. Works offline. menu (string) – Menu bar options include: none - No menu or buttons. zoom - Just zoom buttons. all (Default) - Menu and button bar (requires Bootstrap). scroll_behavior (string) – Scroll behavior options: pan - Pan the map. zoom - Zoom the map. none (Default) - No scroll events. enable_editing (Boolean) – Enable the map editing modes. enable_keys (Boolean) – Enable keyboard shortcuts. minified_js (Boolean) – If True, use the minified version of js files. If js_source is dev, then this option is ignored. never_ask_before_quit (Boolean) – Never display an alert asking if you want to leave the page. By default, this message is displayed if enable_editing is True.

display_in_notebook(js_source=u'web', menu=u'zoom', scroll_behavior=u'none', minified_js=True, height=500)¶

Embed the Map within the current IPython Notebook.

Parameters:

js_source (string) – Can be one of the following: web (Default) - Use JavaScript files from escher.github.io. local - Use compiled JavaScript files in the local Escher installation. Works offline. dev - Use the local, uncompiled development files. Works offline. menu (string) – Menu bar options include: none - No menu or buttons. zoom - Just zoom buttons. Note: The all menu option does not work in an IPython notebook. scroll_behavior (string) – Scroll behavior options: pan - Pan the map. zoom - Zoom the map. none - (Default) No scroll events. minified_js (Boolean) – If True, use the minified version of js files. If js_source is dev, then this option is ignored. height – Height of the HTML container.

save_html(filepath=None, js_source=u'web', menu=u'all', scroll_behavior=u'pan', enable_editing=True, enable_keys=True, minified_js=True, never_ask_before_quit=False, static_site_index_json=None)¶

Save an HTML file containing the map.

Parameters:

filepath (string) – The HTML file will be saved to this location. js_source (string) – Can be one of the following: web (Default) - Use JavaScript files from escher.github.io. local - Use compiled JavaScript files in the local Escher installation. Works offline. dev - Use the local, uncompiled development files. Works offline. menu (string) – Menu bar options include: none - No menu or buttons. zoom - Just zoom buttons. all (Default) - Menu and button bar (requires Bootstrap). scroll_behavior (string) – Scroll behavior options: pan - Pan the map. zoom - Zoom the map. none (Default) - No scroll events. enable_editing (Boolean) – Enable the map editing modes. enable_keys (Boolean) – Enable keyboard shortcuts. minified_js (Boolean) – If True, use the minified version of js files. If js_source is dev, then this option is ignored. height (number) – Height of the HTML container. never_ask_before_quit (Boolean) – Never display an alert asking if you want to leave the page. By default, this message is displayed if enable_editing is True. static_site_index_json (string) – The index, as a JSON string, for the static site. Use javascript to parse the URL options. Used for generating static pages (see static_site.py).

License¶

Escher and EscherConverter are distributed under the MIT license.