Visualization Grammar¶

Genome browser applications typically couple the visual representations to specific file formats and provide few customization options. GenomeSpy has a more abstract approach to visualization, providing combinatorial building blocks such as marks, transformations, and scales. As a result, users can author tailored visualizations that display the underlying data more effectively.

The concept was first introduced in The Grammar of Graphics and developed further in ggplot2 and Vega-Lite.

A dialect of Vega-Lite

The visualization grammar of GenomeSpy is a dialect of Vega-Lite, providing partial compatibility. However, the goals of GenomeSpy and Vega-Lite are different – GenomeSpy is more domain-specific and primarily intended for the visualization and analysis of large datasets containing genomic coordinates. Nevertheless, GenomeSpy tries to follow Vega-Lite's grammar where practical, and thus, this documentation has several references to its documentation.

A single view specification¶

Each view specification must have at least the data to be visualized, the mark that will represent the data items, and an encoding that specifies how the fields of data are mapped to the visual channels of the mark. In addition, an optional transform steps allow for modifying the data before they are encoded into mark instances.

{
  "data": { "url": "sincos.csv" },
  "transform": [
    { "type": "formula", "expr": "abs(datum.sin)", "as": "abs(sin)" }
  ],
  "mark": "point",
  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "abs(sin)", "type": "quantitative" },
    "size": { "field": "x", "type": "quantitative" }
  }
}

Properties¶

baseUrl

Type: string

The base URL for relative URL data sources and URL imports. The base URLs are inherited in the view hierarchy unless overridden with this property. By default, the top-level view's base URL equals to the visualization specification's base URL.

configurableVisibility

Type: boolean

Is the visibility configurable interactively from the GenomeSpy App. Configurability requires that the view has an explicitly specified name that is unique within its import scope.

Default: false for children of layer, true for others.

data

Specifies a data source. If omitted, the data source is inherited from the parent view.

description

Type: string | string[]

A description of the view. Can be used for documentation. The description of the top-level view is shown in the toolbar of the GenomeSpy App.

domainInert

Type: boolean

If true, this view and its descendants do not contribute to scale domains. Child views inherit this flag automatically.

Default value: false

encoding

Type: Encoding

Specifies how data are encoded using the visual channels.

height

Type: SizeDef | number | Step | "container"

Height of the view. If a number, it is interpreted as pixels. Check child sizing for details.

Default value: "container"

mark Required

The graphical mark presenting the data objects.

name

Type: string

An explicit name used to address the view. It is recommended to keep names unique among siblings. In the App (where view state is bookmarkable), the name must be unique within its import scope for views with configurable visibility, etc.

opacity

Type: number | DynamicOpacity | ExprRef

Opacity of the view and all its children.

This can be:

a fixed number between 0 and 1
an expression reference (ExprRef)
a DynamicOpacity definition for zoom-dependent opacity

Dynamic opacity is useful for semantic zooming where layers are faded in and out as the user zooms.

Example:

json "opacity": { "unitsPerPixel": [100000, 40000], "values": [0, 1] }

In this example, the view fades in while zooming in from 100 000 to 40 000 units per pixel.

Default value: 1.0

padding

Type: Paddings | number

Padding applied to the view. Accepts either a number representing pixels or an object specifying separate paddings for each edge.

Examples: - padding: 10 - padding: { top: 10, right: 20, bottom: 10, left: 20 }

Default value: 0

params

Type: array

Dynamic variables that parameterize a visualization.

resolve

Type: object

Specifies how scales and axes are resolved in the view hierarchy.

templates

Type: object

TODO

title

Type: string | Title

View title. N.B.: Currently, GenomeSpy doesn't do bound calculation, and you need to manually specify proper padding for the view to ensure that the title is visible.

transform

Type: array

An array of transformations applied to the data before visual encoding.

view

Type: ViewBackground

The background of the view, including fill, stroke, and stroke width.

viewportHeight

Type: SizeDef | number | "container"

Optional viewport height of the view. If the view size exceeds the viewport height, it will be shown with scrollbars. This property implicitly enables clipping.

Default: null (same as height)

viewportWidth

Type: SizeDef | number | "container"

Optional viewport width of the view. If the view size exceeds the viewport width, it will be shown with scrollbars. This property implicitly enables clipping.

Default: null (same as width)

visible

Type: boolean

The default visibility of the view. An invisible view is removed from the layout and not rendered. For context, see toggleable view visibility.

Default: true

width

Type: SizeDef | number | Step | "container"

Width of the view. If a number, it is interpreted as pixels. Check child sizing for details.

Default: "container"

View composition for more complex visualizations¶

View composition allows for building more complex visualizations from multiple single-view specifications. For example, the layer operator allows creation of custom glyphs and the concatenation operators enables stacked layouts resembling genome browsers with multiple tracks.