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¶

aggregateSamples

Type: array

Specifies views that aggregate multiple samples within the GenomeSpy App.

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 in within the view hierarchy.

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.

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 internal name that can be used for referring the view. For referencing purposes, the name should be unique within the view hierarchy.

opacity

Type: number | DynamicOpacity | ExprRef

Opacity of the view and all its children. Allows implementing semantic zooming where the layers are faded in and out as the user zooms in and out.

TODO: Write proper documentation with examples.

Default: 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

Templates that can be reused within the view specification by importing them with the template key.

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.