Skip to content

Python API Reference

Jump to bottom Edit New page
zakandrewking edited this page Sep 24, 2014 · 16 revisions

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/.

Using custom maps

There are three ways to use Escher json files (maps and models) in the Python interface.

  1. Pass JSON strings to escher.Builder()

The Builder class accepts two arguments, map_json and model_json, that accept strings of JSON data for maps and models. For example, this code loads a local JSON file for an escher map, and generates a Builder for the map:

with open('my_map.json', 'r') as f:
    json_string = f.read()
b = escher.Builder(map_json=json_string)
  1. Add maps and models to the cache directory.

Any maps and models in the cache directory are available by name. Use the function escher.get_cache_dir() to locate the cache directory in your filesystem. Then, you can access those files by passing their names to the arguments map_name and model_name. For example, if the file my_map.json is in the directory ~/my/cache_dir/maps, then load that map with this code snippet:

b = escher.Builder(map_name='my_map')
  1. Serve maps and models from another URL.

You can serve maps and models from any URL, by changing the value of escher.urls.map_download and escher.urls.model_download to appropriate URLs. For instance:

escher.urls.map_download = 'http://my.server.org/escher_maps'
b = escher.Builder(map_name='my_map_on_the_web')

Javascript Source

The js_source option lets you choose where to load the Escher library from. Note: In the IPython notebook, do not try to mix js_source options. Once Escher is loaded from the web, it will not load again from the local Escher installation.

API

escher.Builder

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

Generates a new Builder object.

  • map_name: a string specifying a map to be downloaded from the Escher web server. 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.

  • map_json: a json string, or a file path to a json file, or a URL specifying a json file to be downloaded.

  • model_name: a string specifying a model to be downloaded from the Escher web server. This is the model ID available from http://zakandrewking.github.io/escher/. The map data will be downloaded when Builder() is called, if it is not already cached.

  • model_json: a json string, or a file path to a json file, or a URL specifying a json file to be downloaded.

  • reaction_data: a dictionary with keys that correspond to reaction ids and values that will be mapped to reaction arrows and labels.

  • reaction_data: a dictionary with keys that correspond to metabolite ids and values that will be mapped to metabolite nodes and labels.

  • local_host: a hostname that will be used for any local files in dev mode. Defaults to the current host.

  • embedded_css: a css string to be embedded with the Escher SVG. Required for js_source 'dev' or 'local'

  • 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.

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'].

Add a custom footer
Add a custom sidebar
Clone this wiki locally