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:

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

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

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

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

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

Plots have a few widgets for various special use cases.

Plot Curtain

The plot curtain is an HTML overlay that obscures the entire plot. It can be styled arbitrarily and display arbitrary messages. It is useful for reporting error messages visually to an end user when the error renders the plot unusable.

Use the curtain by invoking the following methods:

• plot.curtain.show([content[, css]])
  Generate the curtain. Any content (string) argument passed will be displayed in the curtain as raw HTML. CSS (object) can be passed which will apply styles to the curtain and its content.

• plot.curtain.update([content[, css]])
  Update the content and css of the curtain that's currently being shown. This method also adjusts the size and positioning of the curtain to ensure it still covers the entire plot with no overlap.

• plot.curtain.hide()
  Remove the curtain.

Plot Loader

The plot loader is a small HTML overlay that appears in the lower left corner of the plot. It cannot be styled arbitrarily but can show a custom message and show a minimalist loading bar that can be updated to specific completion percentages or be animated.

Use the loader by invoking the following methods:

• plot.loader.show([content]])
  Generate the loader. Any content (string) argument passed will be displayed in the string as raw HTML. If no content is supplied the message in the loader will default to "Loading..."

• plot.loader.update([content[, percent]])
  Update the content (string) and, optionally, the percent (number) complete of the loader that's currently being shown. This method also adjusts the positioning of the loader to ensure it still appears in the lower left corner. Percents will automatically be limited to a range of 1 to 100 and, if passed, will stop all animations in progress.

• plot.loader.setPercentCompleted(percent)
  Sets the loading bar in the loader to precentage width equal to the percent (number) value passed. Percents will automatically be limited to a range of 1 to 100. Will stop all animations in progress.

• plot.loader.animate()
  Adds a class to the loading bar that makes it loop infinitely in a loading animation.

• plot.loader.hide()
  Remove the loader.

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.

• responsive_resize - Boolean
  Whether and the LocusZoom plot should automatically resize itself to fill the width of its containing element while maintaining its aspect ratio. When set to true, as the containing element of a plot changes size (e.g. when the browser window is resized, mobile device is flipped portrait/landscape, etc.) the plot will, in most browser environments, automatically detect the change and redraw the plot to fill the newly available width while maintaining the existing plot aspect ratio (within the bounds set by the layout minimums). Note: apply the class lz-container-responsive to the containing element for best results.

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.