Python API Reference

escher includes a Python package for building maps. Maps generated with the Python API can be viewed in a browser, shared as standalone HTML files, or displayed directly in an IPython Notebook.

Dependencies

• Jinja2
• tornado
• cobra, 0.3.0b1 or later

Installation

The Python package for Escher can be installed using pip:

pip install escher --pre

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

python setup.py install

Maps

When a Map object is created, the map data is automatically downloaded and cached locally. A list of map IDs that are available are kept up-to-date at http://zakandrewking.github.io/escher/.

API

escher.Builder

Builder(map_name="e-coli-core", flux={})

Generates a new Builder object.

• map_name: This is the map ID available from http://zakandrewking.github.io/escher/. The map data will be downloaded when Builder() is called, if it is not already cached.

• flux: A dictionary with reaction IDs as keys and flux values as keys.

save_html(outfilepath=None)

Outputs the maps as a standalone HTML file. Supply outfilepath to save the file to a particular location. If outfilepath is not supplied, then a temporary file is generated and displayed. Paste this file path into a web browser to view the map.

display_in_browser()

Generates a temporary HTML file and launches it with the default application. Note: If .html files are associated with an application other than your browser, then this function will not behave as advertised. The create_standalone_html() function is a safer bet.

_repr_html()

Generates the html map view. When a Map is generated in an IPython Notebook (and not assigned to a variable), then _repr_html() is called automatically and the map will appear.

Setting the data scale

The following functions can be used to set the scale for reaction and metabolite data in Escher. For more details on how the underlying scales work, see the d3.js documentation on quantitative scales.

The easiest way to use data scales is to leave both domains on auto (the default). Then, use the range functions listed below to change the color and size of metabolite circles and reaction arrows. Pass a 3 element array to each function to specify the colors and sizes. The the range entries mean one of the following, depending on whether the minimum value is less that zero:

color:

• [color at 0, color at data minimum, color at data maximum] (0 < minimum)
• [color at data minimum, color at 0, color at data maximum] (0 > minimum)

size:

• [size at 0, size at data minimum, size at data maximum] (0 < minimum)
• [size at data minimum, size at 0, size at data maximum] (0 > minimum)

Play around with different color and size ranges to get the effect you want. Or, edit all of these settings in the web interface, using the Data > Settings menu.

set_auto_metabolite_domain(auto_metabolite_domain)

set_auto_reaction_domain(auto_reaction_domain)

If True, then the scale domain will be set automatically to three values: 0, the data minimum, and the data maximum. If False, the the domain can be set manually with the functions below. By default, both properties are set to True.

set_metabolite_domain(domain_array)

set_reaction_domain(domain_array)

domain_array is an array of numbers representing the scale domain. By default, these setting are ignored in favor of automatic domain setting.

set_reaction_size_range(range_array)

range_array is an array of ordered reaction line widths, corresponding to the entries in the metabolite domain array. If set_auto_metabolite_domain is True, then the range must be an array of length 3.

set_metabolite_size_range(range_array)

range_array is an array of ordered metabolite circle sizes, corresponding to the entries in the metabolite domain array. If set_auto_metabolite_domain is True, then the range must be an array of length 3.

set_reaction_color_range(range_array)

range_array is an array of ordered reaction arrow colors, corresponding to the entries in the metabolite domain array. If set_auto_metabolite_domain is True, then the range must be an array of length 3. Colors are specified as strings, and any valid CSS color string is OK (e.g. 'blue', 'rgb(100,0,0)', or '#faa').

set_metabolite_color_range(range_array)

range_array is an array of ordered metabolite circle colors, corresponding to the entries in the metabolite domain array. If set_auto_metabolite_domain is True, then the range must be an array of length 3. Colors are specified as strings, and any valid CSS color string is OK (e.g. 'blue', 'rgb(100,0,0)', or '#faa').

set_reaction_styles(styles_array)

set_metabolite_styles(styles_array)

The styles_array can include any of the following values. If a value is present, it has the following effect:

• 'abs' - Use the absolute value of the dataset entries.
• 'size' - Change the size according to the size range.
• 'color' - Change the color according to the color range.
• 'text' - Change the text labels to show data values.

By default, styles_array for reactions is ['abs', 'size', 'color', 'text'] and styles_array for metabolites is ['size', 'color', 'text'].