8. 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).

8.1. Cache

escher.get_cache_dir(name=None)

Get the cache dir as a string.

Parameters:name (string) – An optional subdirectory within the cache
escher.clear_cache(different_cache_dir=None)

Empty the contents of the cache directory.

Parameters:different_cache_dir (string) – (Optional) The directory of another cache. This is mainly for testing.
escher.list_cached_maps()

Return a list of all cached maps.

escher.list_cached_models()

Return a list of all cached models.

escher.list_available_maps()

Return a list of all maps available on the server

escher.list_available_models()

Return a list of all models available on the server