Class: Plot

Plot(id, datasource)

new Plot(id, datasource)

An independent LocusZoom object that renders a unique set of data and subpanels. Many such LocusZoom objects can exist simultaneously on a single page, each having its own layout.

This creates a new plot instance, but does not immediately render it. For practical use, it may be more convenient to use the LocusZoom.populate helper method.

Parameters:
Name Type Attributes Default Description
id String

The ID of the plot. Often corresponds to the ID of the container element on the page where the plot is rendered..
datasource DataSources

Ensemble of data providers used by the plot
layout.state object <optional>

Initial state parameters; the most common options are 'chr', 'start', and 'end' to specify initial region view
layout.width number <optional>
 800

The width of the plot and all child panels
layout.min_width number <optional>
 400

Do not allow the panel to be resized below this width
layout.min_region_scale number <optional>

The minimum region width (do not allow the user to zoom smaller than this region size)
layout.max_region_scale number <optional>

The maximum region width (do not allow the user to zoom wider than this region size)
layout.responsive_resize boolean <optional>
 false

Whether to resize plot width as the screen is resized
layout.panels Array.<Object> <optional>

Configuration options for each panel to be added
layout.toolbar.widgets Array.<module:LocusZoom_Widgets> <optional>

Configuration options for each widget to place on the plot-level toolbar
layout.panel_boundaries boolean <optional>
 true

Whether to show interactive resize handles to change panel dimensions
layout.mouse_guide boolean <optional>
 true

Whether to always show horizontal and vertical dotted lines that intersect at the current location of the mouse pointer. This line spans the entire plot area and is especially useful for plots with multiple panels.
Source:

Members

(protected, static, constant) default_layout :Object

Default/ expected configuration parameters for basic plotting; most plots will override

Type:
  • Object
Source:

(protected) _event_hooks :Object

Known event hooks that the panel can respond to

Type:
  • Object
Source:
See:

id :String

Type:
  • String
Source:

layout :Object

The current layout options for the plot, including the effect of any resizing events or dynamically generated config produced during rendering options.

Type:
  • Object
Source:

panels :Object.<String, Panel>

Direct access to panel instances, keyed by panel ID. Used primarily for introspection/ development.

Type:
Source:

state :Object

Create a shortcut to the state in the layout on the Plot. Tracking in the layout allows the plot to be created with initial state/setup.

Tracks state of the plot, eg start and end position

Type:
  • Object
Source:

Methods

addPanel(layout) → {Panel}

Create a new panel from a layout, and handle the work of initializing and placing the panel on the plot

Parameters:
Name Type Description
layout Object
Source:
Returns:
Type
Panel

applyState(state_changes) → {Promise}

Update state values and trigger a pull for fresh data on all data sources for all data layers

Parameters:
Name Type Description
state_changes Object
Source:
Fires:
Listens to Events:
Returns:

A promise that resolves when all data fetch and update operations are complete

Type
Promise

destroy()

Remove the plot from the page, and clean up any globally registered event listeners

Internally, the plot retains references to some nodes via selectors; it may be useful to delete the plot instance after calling this method

Source:

emit(event, eventData) → {Plot}

Handle running of event hooks when an event is emitted

Parameters:
Name Type Description
event string

A known event name
eventData *

Data or event description that will be passed to the event listener
Source:
See:
Returns:
Type
Plot

mutateLayout()

Plots can change how data is displayed by layout mutations. In rare cases, such as swapping from one source of LD to another, these layout mutations won't be picked up instantly. This method notifies the plot to recalculate any cached properties, like data fetching logic, that might depend on initial layout. It does not trigger a re-render by itself.

Source:

off(event, hookopt) → {Plot}

Remove one or more previously defined event listeners

Parameters:
Name Type Attributes Description
event String

The name of an event (as defined in event_hooks)
hook eventCallback <optional>

The callback to deregister
Source:
See:
Returns:
Type
Plot

on(event, hook) → {function}

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.

To register a hook for any of these events use plot.on('event_name', function() {}).

There can be arbitrarily many functions registered to the same event. They will be executed in the order they were registered.

Parameters:
Name Type Description
event String

The name of an event. Consult documentation for the names of built-in events.
hook eventCallback
Source:
See:
Returns:

The registered event listener

Type
function

refresh() → {Promise}

Refresh (or fetch) a plot's data from sources, regardless of whether position or state has changed

Source:
Returns:
Type
Promise

removePanel(id) → {Plot}

Remove the panel from the plot, and clear any state, tooltips, or other visual elements belonging to nested content

Parameters:
Name Type Description
id String
Source:
Fires:
Returns:
Type
Plot

subscribeToData(optsopt, success_callback) → {function}

Allow newly fetched data to be made available outside the LocusZoom plot. For example, a callback could be registered to draw an HTML table of top GWAS hits, and update that table whenever the plot region changes.

This is a convenience method for external hooks. It registers an event listener and returns parsed data, using the same fields syntax and underlying methods as data layers.

Parameters:
Name Type Attributes Description
opts Object <optional>

Options

Properties
Name Type Attributes Default Description
from_layer String <optional>
 null

The ID string (panel_id.layer_id) of a specific data layer to be watched.
namespace Object <optional>

An object specifying where to find external data. See data layer documentation for details.
data_operations Object <optional>

An array of data operations. If more than one source of data is requested, this is usually required in order to specify dependency order and join operations. See data layer documentation for details.
onerror externalErrorCallback <optional>

User defined function that is automatically called if a problem occurs during the data request or subsequent callback operations
success_callback externalDataCallback

Used defined function that is automatically called any time that new data is received by the plot. Receives two arguments: (data, plot).
Source:
Listens to Events:
Returns:

The newly created event listener, to allow for later cleanup/removal

Type
function

trackExternalListener(target, event_name, listener)

Keep a record of event listeners that are defined outside of the LocusZoom boundary (and therefore would not get cleaned up when the plot was removed from the DOM). For example, window resize or mouse events. This allows safe cleanup of the plot on removal from the page. This method is useful for authors of LocusZoom plugins.

Parameters:
Name Type Description
target Node

The node on which the listener has been defined
event_name String
listener function

The handle for the event listener to be cleaned up
Source: