Skip to content

Layouts

Jump to bottom
Christopher Clark edited this page Nov 23, 2016 · 6 revisions

API Reference ▸ Layouts

Layouts

A Layout is a JSON object that is used to describe the composition and behavior of an entire LocusZoom plot or a component therein. As true JSON layouts cannot contain functions or special JavaScript literals such as NaN or Infinity.

Layouts are LocusZoom's "structure", and any subdivision of a LocusZoom plot is therefore described with a layout. For example, a data layer may be described with a layout and that data layer may be included in the layout of its containing panel, which in turn may be included in the layout of its containing plot. Any time a JSON object is used to describe the composition of a piece of a LocusZoom plot, that object is referred to as a layout.

In this documentation the individual elements in a layout are called directives. Depending on what the layout will be consumed to create there may be different directives that do different things. For example, supported directives for a data layer may differ from those used for a legend, or from a panel.

Refer to the following pages for specific documentation of supported directives by layout type:

User-Defined Layouts

Since any layout is just a JSON object it is always possible to build a new layout from scratch. For example, defining a layout for populating a new plot:

var layout = {
  width: 100,
  height: 100,
  panels: [
    {
      id: "panel_1",
      /* more panel layout directives here... */
    }
  ]
}
var plot = LocusZoom.populate("#element", datasources, layout);

Pre-Defined / Stored Layouts

The LocusZoom library comes with a variety of pre-defined layouts that can serve as completed plug-and-play layouts or as partial layouts to be modified as a jumping-off point.

These are accessed via the Layouts object.

List Stored Layouts with LocusZoom.Layouts.list()

Stored layouts have a type and a name (a string identifier). List all available layouts by type like so:

> LocusZoom.Layouts.list()
Object {plot: Array[3], panel: Array[5], data_layer: Array[7], dashboard: Array[2]}

And list the names of stored layouts of a given type by passing a type as the only argument:

> LocusZoom.Layouts.list("plot")
["standard_association", "standard_phewas", "interval_association"]

Get a Stored Layout with LocusZoom.Layouts.get()

To get a stored layout pass a type and a name to LocusZoom.Layouts.get() like so:

> var layout = LocusZoom.Layouts.get("plot", "standard_association");
Object {state: Object, width: 800, height: 450, resizable: "responsive", min_region_scale: 20000...}

An object detailing modifications to a layout can be passed in as a second argument. This will cause the returned layout to have the modifications automatically merged in:

> var layout = LocusZoom.Layouts.get("plot", "standard_association", { width: 1000 });
Object {state: Object, width: 1000, height: 450, resizable: "responsive", min_region_scale: 20000...}

Store New Layouts with LocusZoom.Layouts.add()

LocusZoom's Layout storage can be used to store custom layouts at run-time. Pass a type and a name to the add() method to register the layout:

LocusZoom.Layouts.add("plot", "my_custom_plot", { width: 1000, height: 1000... });

Note that this may be useful any time a layout may be reused and modified in the process. This is because of JavaScript's assign-by-reference behavior with respect to objects... Assigning a layout to a variable and then "copying" that object by assigning to another variable doesn't actually make a copy; both variables are references to the same object in memory and editing one will edit the other. When getting a layout via the LocusZoom.Layouts object, however, completely new objects that are not shared among other reference variables are returned, ensuring the layout can be edited without creating conflicts or strange behavior.

Merge Two Layouts with LocusZoom.Layouts.merge()

If there are two layout objects each representing pretty much the same thing, one being a "baseline" layout (e.g. default values) and the other being a "customizations" layout (new values to overwrite defaults) then the merge method will cleanly combine them and return a new object with no shared references. Use like so:

var baseline = {
  width: 800, min_width: 400
};
var customizations = {
  width: 1000, height: 1000
};
var new_layout = LocusZoom.Layouts.merge(customizations, baseline);
...
Object {width: 1000, min_width: 400, height: 1000}

Note that the same method is used internally when using LocusZoom.Layouts.get() and passing a modifications object (the stored layout being the baseline and the modifications being the customizations to apply).

Clone this wiki locally