# 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:
  - components/plot.js, line 228

### Members

#### (protected, static, constant) default_layout :Object

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

##### Type:

- Object

Source:
  - components/plot.js, line 17

#### (protected) _event_hooks :Object

Known event hooks that the panel can respond to

##### Type:

- Object

Source:
  - components/plot.js, line 330
See:
  - event:any_lz_event for a list of pre-defined events commonly used by LocusZoom

#### id :String

##### Type:

- String

Source:
  - components/plot.js, line 245

#### 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:
  - components/plot.js, line 288

#### panels :Object.<String, Panel>

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

##### Type:

- Object.<String, Panel>

Source:
  - components/plot.js, line 264

#### 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:
  - components/plot.js, line 309

### 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:
  - components/plot.js, line 468

##### 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:
  - components/plot.js, line 738

##### Fires:

- event:data_requested
- event:layout_changed
- event:data_rendered
- event:state_changed
- event:region_changed

##### Listens to Events:

- event:match_requested

##### 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:
  - components/plot.js, line 831

#### 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:
  - components/plot.js, line 422
See:
  - event:any_lz_event for a list of pre-defined events commonly used by LocusZoom

##### 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:
  - components/plot.js, line 865

#### 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:
  - components/plot.js, line 394
See:
  - event:any_lz_event for a list of pre-defined events commonly used by LocusZoom

##### 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:
  - components/plot.js, line 371
See:
  - event:any_lz_event for a list of pre-defined events commonly used by LocusZoom

##### 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:
  - components/plot.js, line 620

##### 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:
  - components/plot.js, line 566

##### Fires:

- event:panel_removed

##### 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:
  - components/plot.js, line 660

##### Listens to Events:

- event:data_rendered
- event:data_from_layer

##### 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:
  - components/plot.js, line 812