Plot

API Reference ▸ Plot

Plot

A Plot is a complete LocusZoom instance. It is the value returned from LocusZoom.populate().

Plot Methods

Once a plot has been created (e.g. the value returned from LocusZoom.populate() there are various supported methods for interacting with the plot:

• addPanel(layout)
  Add a new panel with the panel layout (object) provided. Will automatically update the dimensions of the plot to accommodate the new panel.

• removePanel(id)
  Remove a panel by ID (string). Will automatically update the dimensions of the plot to account for the panel's removal.

• setDimensions([width, height])
  Set the total dimensions for the plot. If passed with no arguments will calculate optimal size based on layout directives and the available area on the page. If passed discrete width (number) and height (number) will attempt to resize the plot to them, but may be limited by minimum dimensions defined on the plot or panels.

• applyState(state)
  Accepts a state (object) to be applied to the plot's layout. Properties of the state argument are merged with the existing state on the plot. This triggers requests to get new data for the updated state values across all panels and emits a data_requested event.

• refresh()
  Shortcut to apply an empty state object with applyState. In other words this triggers a call to request all data for the plot using all existing state values, essentially re-requesting and re-rendering all existing data.

Plot Events and Hooks

There are several events that a LocusZoom plot can "emit" when appropriate and LocusZoom supports registering "hooks" for these events which are essentially custom functions intended to fire at certain times.

The following plot-level events are currently supported:

• layout_changed - context: plot
  Any aspect of the plot's layout (including dimensions or state) has changed.

• data_requested - context: plot
  A request for new data from any data source anywhere in the plot has been made.

• data_rendered - context: plot
  Data from a request has been received and rendered.

• element_clicked - context: element A data element in any of the plots panels has been clicked.

To register a hook for any of these events use the plot's on() method like so:

var plot = LocusZoom.populate(selector, data_sources, layout);
plot.on("data_requested", function(){
  console.log("data requested for LocusZoom plot" + this.id);
});
plot.on("data_rendered", function(){
  console.log("data rendered for LocusZoom plot" + this.id);
});

In the above example we log to the console a message containing the plot's ID whenever data is requested and subsequently rendered.

There can be arbitrarily many functions registered to the same event. They will be executed in then order they were registered. The this context bound to each event hook function is dependent on the type of event, as denoted above. For example, when data_requested is emitted the context for this in the event hook will be the plot itself, but when element_clicked is emitted the context for this in the event hook will be the element that was clicked.

Plot Layout

A plot's layout is a serializable object that describes every customizable feature of a LocusZoom plot with nested values. It should only ever contain scalar values, arrays, and objects - no functions!

Example:

var layout = {
  width: 500,
  height: 500,
  panels: {
    positions: {
      origin: { x: 0, y: 0 },
      width: 500,
      height: 250,
      data_layers: {
         positions:
           type: "scatter",
           ...
         }
      }
    },
    ...
  }
};

Supported Layout Directives

• width - Number
  Discrete width, in pixels, of the LocusZoom plot. Must be non-zero. Subject to being limited by min_width.

• height - Number
  Discrete height, in pixels, of the LocusZoom plot. Must be non-zero. Subject to being limited by min_height.

• aspect_ratio - Number
  Aspect ratio for the LocusZoom plot expressed as the evaluation of the plot's width divided by it's height (e.g. an aspect ratio of 8:5 would be 1.6). Must be non-zero.

• min_width - Number
  Minimum discrete width, in pixels, allowable for the LocusZoom plot. May automatically increase to the greatest panels.{$panel_id}.min_width for each $panel_id.

• min_height - Number
  Minimum discrete height, in pixels, allowable for the LocusZoom plot. May automatically increase based on panels.{$panel_id}.min_height and panels.{$panel_id}.proportional_height for each $panel_id.

• panel_boundaries - Boolean
  Whether or not to show draggable boundary elements between panels when the mouse is over the plot that allow for a user to adjust the heights of panels on an individual basis. Defaults to true.

• resizable - String: "manual", "responsive", or null/false
  Whether and how a LocusZoom plot can be automatically resized.

  • "manual" - Provide a resize handle in the lower right corner of the plot that can be dragged by the user to resize the plot arbitrarily
  • "responsive" - Attempt to expand the plot to fill 100% of the available width of the containing element at all times. Attach a namespaced window.resize event listener to automatically resize the plot as resizing the browser window changes the available width in the containing element. Note: apply the class lz-container-responsive to the containing element for best results.
  • false / null - Do not allow resizing of the plot.

Controls

• controls - Object
  The controls element provides plot-wide information and UI elements in an HTML element that appears below the plot itself. The following parameters for the controls element are supported:

  • controls.show - String: "always", "onmouseover", or null/false
    When to show the controls element. Set to always to display the controls element at all times, set to onmouseover to only show the controls element when the mouse is over the plot, and set to null or false to prevent the controls element from being rendered.

  • controls.hide_delay - Number
    Number of milliseconds to set for a timeout to hide the controls element when the mouse exits the plot. Only applies when controls.show is set to onmouseover. Defaults to 300.

State

• state - Object
  The state contains information describing the current parameters used to query/filter data and current selections and/or customizations by the end user. For more information see State.

Panels

• panels - Object
  An object describing all Panels in the plot. For more information see Panels.