Skip to content

Data Layer

Jump to bottom
Christopher Clark edited this page Dec 12, 2016 · 25 revisions

API Reference ▸ Data Layer

Data Layer

A data layer is a layer in terms of depth of z-index within a panel for displaying data. It is clipped by the panel's defined clip area and can be one of any supported type. Depending on the type of the data layer it will be able to display different data and support different layout directives.

Data Layer Layout

A data layer'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!

Scalable Layout Directives

Several directives supported by data layers may be scalable, and will be denoted as such. Scalable directives are those that can be defined statically as a scalar value (string or number), one or more Scale Functions, or a combination thereof.

Supported Layout Directives - All Data Layer Types

  • type - String
    The name of a defined DataLayer class. LocusZoom Core comes pre-supplied with several types of Data Layers already defined and provides an API to create custom Data Layers as needed. See Data Layer Types for more details.

  • fields - Array
    An array of strings that map to valid fields in the Data Sources. These values will be processed during every request for data so that every data object stored in the Data Layer has each of these values as a named property.

  • color - String or Object, Scalable
    A string representing a uniform color for data represented by a data layer or an object describing a dynamic coloring scheme.

  • z_index - Number
    An integer representing the order in which a data layer should be rendered relative to other data layers. Data layers with higher z_index values are rendered above those with lower values. This value will be automatically assigned to a data layer as it is added through the normal parsing of a layout object during initialization, and any value defined here may be overridden to ensure that all data layers for a panel have a meaningful integer z_index beginning at 0.

Axes

  • (x|y)_axis - Object
    An object that attaches a data field to an axis and sets limits on the range of the data displayed.

    For a panel with axes, both axes (data_layer.x_axis and data_layer.y_axis) should be defined as objects with at least a field defined on each for a data layer to render properly. Not all panels and data layers have axes in the traditional sense. If a panel / data layer does not define an x_axis, for example, then the x_axis (shown or not) is assumed to be genetic position and the range of the axis shown assumed to be bounded by the start and end values defined in the State.

    • (x|y)_axis.field - String
      Name of the field to map to the axis. The field name used here should also be present in data_layer.fields.

    • y_axis.axis - Number: 1 or 2
      Number signifying which of the two available y axes to bind this data layer. Only values 1 (left y-axis) and 2 (right y-axis) are valid. If not set, or set to any value other than 1 or 2, this value will default to 1.

    • (x|y)_axis.floor - Number
      Discrete minimum value for data points on the axis. By default the lower limit on the axis will be the lower limit of the extent of the data set mapped to the axis. This value can override that automatic limit by forcing a specific minimum value.

    • (x|y)_axis.ceiling - Number
      Discrete maximum value for data points on the axis. By default the upper limit on the axis will be the upper limit of the extent of the data set mapped to the axis. This value can override that automatic limit by forcing a specific maximum value.

    • (x|y)_axis.lower_buffer - Number
      Amount to expand to the lower end of an axis as a proportion of the extent of the data. For instance, if a data ranges from 30 to 70 and the lower buffer is set to 0.25 then the lower end of the axis will be expanded by 25% of the extent of the data (70 - 30 = 40 units), or 10 units, dropping the lower end of the axis to 20. Any buffer defined here will be overridden if a floor is also defined.

    • (x|y)_axis.upper_buffer - Number
      Amount to expand to the upper end of an axis as a proportion of the extent of the data. For instance, if a data ranges from 0 to 50 and the upper buffer is set to 0.1 then the upper end of the axis will be expanded by 10% of the extent of the data (50 - 0 = 50 units), or 5 units, expanding the upper end of the axis to 55. Any buffer defined here will be overridden if a ceiling is also defined.

    • (x|y)_axis.min_extent - Array
      A discrete extent to behave as the minimum low and high for the axis. This should be array of exactly two numbers. For example, a min_extent of [ 0, 10 ] will ensure that the axis will at least range from 0 to 10 regardless of the data mapped to it. If the data or the data combined with lower_buffer and/or upper_buffer expands beyond the minimum extent in either direction then the axis will expand beyond the minimum extent to follow suit. Either value in the min_extent array may be overridden by a discrete floor or ceiling value.

Highlight and Select Behavior

LocusZoom data layers support the binding of mouse events to categorize individual data elements as highlighted or selected. The State object keeps arrays of element IDs for all highlighted and selected elements on each data layer to be used for further interaction logic. The act of highlighting or selecting an element also applies data element CSS classes that are suffixed (e.g. with -highlighted or -selected) to denote the status visually.

The data layer layout supports a variety of directives to explicitly describe when the statuses of highlighted and selected are to be applied, or removed, for elements in the data layer:

  • highlighted - Object
    An object describing when an element's highlighted status should be enabled, disabled or toggled.

  • highlighted.(onmouseover|onmouseout|onclick|onctrlclick|onshiftclick|onctrlshiftclick) - String
    A string describing the preferred highlighted status of an element when the given mouse action occurs on it. Supported values are "on" (ensure the element is highlighted), "off" (ensure the element is not highlighted), "toggle" (if the element is highlighted then unhighlight it and vice versa), and "toggle_exclusive" (if the element is highlighted then unhighlight it and vice versa, and if the new status is highlighted then unhighlight all other elements, enforcing only one highlighted element at a time).

  • selected - Object
    An object describing when an element's selected status should be enabled, disabled or toggled.

  • selected.(onmouseover|onmouseout|onclick|onctrlclick|onshiftclick|onctrlshiftclick) - String
    A string describing the preferred selected status of an element when the given mouse action occurs on it. Supported values are "on" (ensure the element is selected), "off" (ensure the element is not selected), "toggle" (if the element is selected then unselect it and vice versa), and "toggle_exclusive" (if the element is selected then unselect it and vice versa, and if the new status is selected then unselect all other elements, enforcing only one selected element at a time).

Tool Tips

  • tooltip - Object
    An object that defines the content and behavior of a tool tip to be displayed when interacting with elements in the data layer. All data layers render tool tips visually the same way, but each data layer has custom logic to position a tool tip relative to an element.

  • tooltip.(show|hide) - String or Object
    This parameter encodes the logic for whether a tool tip should be shown or hidden for an element depending on its highlighted and/or selected statuses. Define logic in terms of the strings "highlighted", "unhighlighted", "selected", and "unselected". As a simple example:

    tooltip: { show: "highlighted", hide: "unhighlighted" }

    This will show (create) the tool tip when the element is highlighted and hide (destroy) the tool tip when the element is unhighlighted, a status defined by the highlighted parameter of the data layer.

    More complex boolean combinations of the four available statuses can be done with an object/array syntax. For example:

    tooltip: { show: { or: ["highlighted", "selected"] }, hide: { and: ["unhighlighted","unselected] } }

    This will ensure that a tool tip is should on any element that is highlighted or selected or both, and ensure that tool tips are not shown for elements that are neither highlighted nor selected. When the internal logic is triggered to interpret these directives relative to an element's status a tool tip will only be shown if its show logic resolves to true and its hide logic resolves to false (e.g. if both show and hide resolve to true, no tool tip will be shown).

  • tooltip.closable - Boolean
    Whether a tool tip should render a "close" button in the upper right corner. When clicked the tool tip will be destroyed. Subsequent mouse events on an element that would cause a tool tip to be shown will recreate the tool tip. By default this is not defined, and therefore close buttons will not be rendered.

  • tooltip.html - String
    HTML to render inside the tool tip. Any data fields that are present in the data layer's fields directive can be resolved to element-specific values inside a tool tip by using double-curly-bracket notation. For example: "Species: {{animal}}" will attempt to resolve {{animal}} to the value of the animal field on the data bound to the element when the tool tip is rendered. Such field declarations must match the elements in the fields array exactly, so should include namespaces and/or transformations if present in the fields array definition.

Legend

  • legend - Array
    A Legend data layer layout array. The contents of the array should be objects describing individual elements to be shown in the legend, which the parent panel will aggregate together with legend elements from sibling data layers.

Transitions

  • transition - Object
    An object that defines how data in the data layer should transition when updated. If defined then all data layer types that support transitions will transition updates to data. By default transitions are not defined for any data layer type.

  • transition.duration - Number
    Number of milliseconds for the transition to take place. If a transition object is defined in the layout, but this value is not defined, then this will default to 0.

  • transition.ease - String
    Easing method for the transition. See d3.ease documentation for information on building easing method strings. If a transition object is defined in the layout, but this value is not defined, then this will default to "cubic-in-out".

Labels

  • label - Object
    An object that defines simple dynamic text labels for elements on a data layer. Labels differ from tool tips in that they are rendered as SVG elements (and thus are a part of the image that persists when downloading the SVG) and that they will render or not independent of any mouse interaction with the element. Labels may also be implemented with logic to attempt to keep adjacent labels from overlapping one another.

  • label.text - String
    Text to render for the label. Any data fields that are present in the data layer's fields directive can be resolved to element-specific values inside a label by using double-curly-bracket notation. For example: "Species: {{animal}}" will attempt to resolve {{animal}} to the value of the animal field on the data bound to the element when the tool tip is rendered. Such field declarations must match the elements in the fields array exactly, so should include namespaces and/or transformations if present in the fields array definition.

  • label.spacing - Number
    Number of pixels to attempt to fit between labels that are very close to one another. Used when labels are rendered and iterative logic executes to push labels apart that may be overlapping.

  • label.filters - Array
    Array of objects that each represent a filter to determine whether a label should render for the element or not. For example:

filters: [
  {
    field: "height",
    operator: ">=",
    value: 50
  },
  {
    field: "weight",
    operator: "<",
    value: 200
  }
]

In this example each element is evaluated first on its height parameter and then on its weight parameter. Only elements with a height >= 50 and a weight < 200 will have a label rendered.

Data Layer Types

LocusZoom has the following Data Layer types defined in the core:

Genes

The genes Data Layer type implements a visualization of gene/transcript/exon information. It implements a custom tool tip rendering function to position tool tips (if defined) above or below genes depending on where there is available space (relative to the panel).

Genes-Specific Directives

  • bounding_box_padding - Number
    Single value in pixels to be used as top, bottom, left, and right padding from data displayed to represent a given gene to its bounding box. The bounding box is directly displayed when a gene is selected but is otherwise invisible, however it represents the "footprint" of a gene in the data layer when the data layer's render function positions genes on tracks such that none overlap. Thus, a larger bounding_box_padding will give genes more space during automatic positioning. Defaults to 6.

  • exon_height - Number
    Height, in pixels, of each exon in each gene. Defaults to 16.

  • label_exon_spacing - Number
    Spacing in pixels between the baseline of each gene's label and the top of exons for that gene. Defaults to 4.

  • label_font_size - Number
    Font size (letter height) in pixels for each gene's label. Defaults to 12.

  • track_vertical_spacing - Number
    Vertical space between gene tracks, in pixels, in which nothing will be rendered. Defaults to 10.

Interval

The interval Data Layer type implements a visualization of interval annotation track data. These data are expected to be objects with start and end positions that are to be rendered as simple positioned rectangles colored by a key.

Interval-Specific Directives

  • always_hide_legend - Boolean
    Whether or not to always hide the conventional legend. A conventional legend must be defined in the layout in order to generate an annotated y-axis to label tracks in a split-track configuration. By default (when this value is false), merging tracks together will hide any y-axis legend and show a conventional legend. Set this to true, however, to refrain from ever showing that conventional legend while still showing a y-axis-based legend in a split-track configuration. Defaults to false.

  • bounding_box_padding - Number
    Single value in pixels to be used as top, bottom, left, and right padding from data displayed to represent a given gene to its bounding box. The bounding box is directly displayed when a gene is selected but is otherwise invisible, however it represents the "footprint" of a gene in the data layer when the data layer's render function positions genes on tracks such that none overlap. Thus, a larger bounding_box_padding will give genes more space during automatic positioning. Defaults to 2.

  • end_field - String
    Field (as defined in the fields array) that represents an interval's end position. Defaults to "end".

  • split_tracks - Boolean
    Whether to split tracks apart such that each category represented by the values of track_split_field for each interval datum gets its own track (true) or collapse all interval data to as few tracks as possible (false). Defaults to true.

  • start_field - String
    Field (as defined in the fields array) that represents an interval's start position. Defaults to "start".

  • track_height - Number
    Height, in pixels, of each track when rendered. Defaults to 15.

  • track_split_field - String
    Field (as defined in the fields array) that represents the category in which a distinct interval falls into. This is used as the categorizing factor when splitting tracks by category. Defaults to "state_id".

  • track_split_legend_to_y_axis - Number
    Y-axis number to use when splitting tracks and displaying a categorical legend as a y axis. Defaults to 2.

  • track_split_order - String
    Direction to sort tracks when splitting them categorically - "ASC" for ascending and "DESC" for descending. Defaults to "DESC".

  • track_vertical_spacing - Number
    Vertical space between tracks, in pixels, in which nothing will be rendered. Defaults to 3.

Line

The line Data Layer type implements a standard line plot. It implements a custom tool tip rendering function to position a tool tip (if defined) that updates with new values as the mouse moves along the rendered line.

Line-Specific Directives

  • hitarea_width - Number
    Stroke width (in pixels) to apply to invisible hit area rendered over the line. This hit area is used to detect mouse interaction with the line (instead of the line itself to allow for intuitive mouse behavior when working with a thin or dotted line). Note that a wider hit area may decrease the accuracy of the mouse event's position relative to the line. Defaults to 5.

  • interpolate - String
    Interpolation mode for the line to be applied to the line directly using d3's interpolate() method (documentation here). Defaults to linear.

  • style - Object
    CSS styles built as an object to be applied to the line directly using d3's style() method (documentation here).

    Defaults to:

{
  "fill": "transparent",
  "stroke-width": "2px"
}

Scatter

The scatter Data Layer type implements a standard scatter plot. It implements a custom tool tip rendering function to position tool tips (if defined) to the left or right of points depending on where there is available space (relative to the panel).

Scatter-Specific Directives

  • color - See general definition above, Scalable
    Defaults to "#888888".

  • id_field - String
    Which field, as defined in the fields array, is to be used as a unique identifier for individual scatter points. Defaults to id.

  • point_size - Number, Scalable
    Size, in square pixels, to render each point in the scatter plot. For example, a square point with a point_size of 64 will be an 8x8 square. Defaults to 40.

  • point_shape - String, Scalable
    Shape of each point on the data layer as represented by a string. Supported values map to the d3 SVG Symbol Types (i.e.: "circle", "cross", "diamond", "square", "triangle-down", and "triangle-up"). Defaults to "circle".

Clone this wiki locally