Skip to content

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
Type: UrlData | InlineData | NamedData | DynamicCallbackData | LazyData | Generator

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
Type: "rect" | "point" | "rule" | "text" | "link" | RectProps | TextProps | RuleProps | LinkProps | PointProps

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.