9. 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. This is generally used for using the notebook offline and for testing in the IPython Notebook with modified Escher code. An example value for local_host is ‘http://localhost:7778/‘.
  • 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 within a web server.

Keyword Arguments

These are defined in the Javascript API:

  • use_3d_transform
  • enable_search
  • fill_screen
  • zoom_to_element
  • full_screen_button
  • starting_reaction
  • unique_map_id
  • primary_metabolite_radius
  • secondary_metabolite_radius
  • marker_radius
  • gene_font_size
  • hide_secondary_metabolites
  • show_gene_reaction_rules
  • hide_all_labels
  • 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
  • identifiers_on_map
  • highlight_missing
  • allow_building_duplicate_reactions
  • cofactors
  • enable_tooltips

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='127.0.0.1', port=7655, n_retries=50, js_source='web', menu='all', scroll_behavior='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 - No longer necessary with source maps. This now gives the
      same behavior as ‘local’.
  • 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 JavaScript and CSS files.
  • 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='web', menu='zoom', scroll_behavior='none', minified_js=True, height=500, enable_editing=False)

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 - No longer necessary with source maps. This now gives the
      same behavior as ‘local’.
  • 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 JavaScript and CSS files.
  • height – Height of the HTML container.
  • enable_editing (Boolean) – Enable the map editing modes.
save_html(filepath=None, overwrite=False, js_source='web', protocol='https', menu='all', scroll_behavior='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. When js_source is ‘local’, then a new directory will be created with this name.
  • overwrite (Boolean) – Overwrite existing files.
  • 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. To make the dependencies available to the downloaded file, a new directory will be made with the name specified by filepath.
    • dev - No longer necessary with source maps. This now gives the
      same behavior as ‘local’.
  • protocol (string) – The protocol can be ‘http’, ‘https’, or None which indicates a ‘protocol relative URL’, as in //escher.github.io. Ignored if source is local.
  • 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 JavaScript and CSS files.
  • 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).

9.1. Cache

escher.get_cache_dir(versioned=True, name=None)

Get the cache dir as a string, and make the directory if it does not already exist.

Parameters:
  • versioned (Boolean) – Whether to return the versioned path in the cache. Escher maps for the latest version of Escher are found in the versioned directory (versioned = True), but maps for previous versions of Escher can be found by visiting the parent directory (versioned = False).
  • name (string) – An optional subdirectory within the cache. If versioned is False, then name is ignored.
escher.clear_cache(different_cache_dir=None, ask=True)

Empty the contents of the cache directory, including all versions of all maps and models.

Parameters:
  • different_cache_dir (string) – (Optional) The directory of another cache. This is mainly for testing.
  • ask (Boolean) – Whether to ask before deleting.
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