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 oflayer
,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 | PointPropsThe 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 asheight
) 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 aswidth
) 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.