8. JavaScript API

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

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

Arguments:
  • map_data (object) – The data for an Escher map layout. Optional: Pass null to load an empty Builder.
  • model_data (object) – The data for a Cobra model that will be used with the Add Reaction tool to build a layout. Optional: Pass null to load the Builder without a model.
  • embedded_css (string) – The stylesheet for the SVG elements in the Escher map. Optional: Pass null to use the default style.
  • selection (object) – The D3 selection of a HTML element that will hold the Builder. (The selection cannot be a SVG element.) Optional: Pass null to load the Builder in the HTML body.
  • options (object) –
    An object defining any of the following
    options. Optional: Pass null to use all default 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: Chooses a good option by testing the browser) 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.

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

    options.full_screen_button

    (Default: false) Include a button in the user interface for entering full screen mode.

    options.ignore_bootstrap

    (Default: false) Do not use Bootstrap for buttons, even if it available. This is used to embed Escher in a Jupyter notebook where it conflicts with the Jupyter Boostrap installation.

    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 } ]
    

    An array of objects that define points on the data scale.

    Each point is an object with a type attribute. Types can be ‘min’, ‘max’, ‘mean’, ‘Q1’ (first quartile), ‘median’, ‘Q3’ (third quartile), or ‘value’. Each point can have a color attribute that specifies a color with a string (any CSS color specification is allowed, including hex, rgb, and rgba). Each point can have a size attirbute that specifies a reaction thickness as a number. Finally, points with type ‘value’ can have a value attribute that specifies an exact number for pont in the scale.

    NOTE: If ‘min’ or ‘max’ is not provided, Escher automatically adds them. To be completely clear about what you expect to see on the map, it is best to provide ‘min’ and ‘max’ in addition to other scale points.

    Here are examples of each type:

    { type: 'min', color: 'red', size: 12 } Specifies that reactions near the minimum value are red and have thickness 12.

    { type: 'Q1', color: 'rgba(100, 100, 50, 0.5)', size: 12 } Specifies that reactions near the first quartile have the given color, opacity, and thickness.

    { type: 'mean', color: 'rgb(100, 100, 50)', size: 50 } Specifies that reactions near the mean value have the given color and thickness.

    { type: 'value', value: 8.5, color: '#333', size: 50 } Specifies that reactions near 8.5 value have the given color and size.

    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 } ]
    

    An array of objects that define points on the data scale. See the description of options.reaction_scale for an explanation of the format.

    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.

    options.cofactors

    (Default: ['atp', 'adp', 'nad', 'nadh', 'nadp', 'nadph', 'gtp', 'gdp', 'h', 'coa', 'ump', 'h20', 'ppi']) A list of metabolite IDs to treat as cofactors. These will be secondary metabolites in new reactions.

    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).
Arguments:
  • clear_gene_reaction_rules (Boolean) – (Optional, Default: false) In addition to setting the data, also turn of the gene_reaction_rules.