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, axes, titles, and legends. 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.

Unit views¶

A GenomeSpy specification describes a hierarchy of views. A unit view is a leaf in the hierarchy that renders data using a graphical mark. The mark is the only required property. A unit view can define its own data, transform, and encoding, or inherit them from an ancestor composition view. Transforms modify the data before the encoding maps its fields to visual channels of the mark.

{
  "description": "Unit view specification example.",

  "data": { "url": "data/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¶

The following reference lists all properties available on unit views. Most are shared by the different view types and can be used throughout a view hierarchy; mark is specific to unit views.

axes

Type: object

Defines properties for axis resolutions used by this view subtree.

Use this when a composed view shares an axis across child views and the axis settings belong to the composed view rather than an individual encoding. An ancestor declaration shadows the whole declaration of a descendant that targets the same resolution. Declarations in separate sibling subtrees are ambiguous and cause an error.

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.

config

Type: GenomeSpyConfig

Configures defaults for this view subtree.

Properties in child views override properties inherited from ancestors.

cursor

Type: string | ExprRef

Mouse cursor shown while the pointer is inside the view. The deepest matching cursor wins: mark cursor first, then the pointed view, then ancestor views outward toward the root.

Default value: browser default

data

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

datasets

Type: object

Named datasets available to this view and its descendants.

A descendant declaration with the same name shadows this declaration. Declare named data here to establish reliable lexical scope and enable scoped runtime updates.

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 | ExprRef | "container"

Height of the view. If a number, it is interpreted as pixels. If an expression reference is provided, it must resolve to a number or "container". Check child sizing for details.

Default value: "container"

legends

Type: object

Defines properties for legend resolutions used by this view subtree.

Use this when a composed view shares a legend across child views and the legend settings belong to the composed view rather than an individual encoding. An ancestor declaration shadows the whole declaration of a descendant that targets the same resolution. Declarations in separate sibling subtrees are ambiguous and cause an error.

mark Required

The graphical mark presenting the rows.

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

overhang

Type: OverhangConfig

Controls whether external overhang on each edge reserves layout space. Setting an edge to false lets axes, titles, legends, or custom view overhang overlap nearby content while remaining visible.

Default value: all edges reserve overhang

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, axes, and legends are resolved in the view hierarchy.

If legend resolution is not configured explicitly, it follows the corresponding scale resolution.

scales

Type: object

Defines properties for scale resolutions used by this view subtree.

Use this when a composed view shares a scale across child views and the scale settings, such as the visible domain, belong to the composed view rather than an individual encoding. An ancestor declaration shadows the whole declaration of a descendant that targets the same resolution. Declarations in separate sibling subtrees are ambiguous and cause an error. Expression references in these scale properties use this view's parameter scope and can access parameters declared here or on ancestors.

templates

Type: object

TODO

title

Type: string | Title

View title.

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 | ExprRef | "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. If an expression reference is provided, it must resolve to a number or "container".

Default: null (same as height)

viewportWidth

Type: SizeDef | number | ExprRef | "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. If an expression reference is provided, it must resolve to a number or "container".

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 | ExprRef | "container"

Width of the view. If a number, it is interpreted as pixels. If an expression reference is provided, it must resolve to a number or "container". Check child sizing for details.

Default: "container"

zindex

Type: number

Z-order among sibling views in a composition. Higher values render later. Views with equal values render in declaration order. This does not affect layout order.

Default value: 0

View composition¶

Composition views arrange child views into a hierarchy. For example, layer overlays views to create custom glyphs, while the concatenation operators arrange views into tracks or grids. Common properties such as data, transform, and encoding can be defined on a composition view and inherited by its descendants.

Schema-assisted editing¶

GenomeSpy publishes a JSON Schema that JSON-aware editors can use for completion, hover documentation, and validation. Add $schema to the root of a Core specification:

{
  "$schema": "https://cdn.jsdelivr.net/npm/@genome-spy/core/dist/schema.json",
  "data": { "url": "data/example.csv" },
  "mark": "point",
  "encoding": {}
}

Use the @genome-spy/app schema instead for sample collection specifications. For reproducible editing, pin the schema to the same package version as the GenomeSpy runtime by adding @VERSION after the package name. The Playground configures the Core schema automatically.

The inline examples in this documentation omit $schema to keep them concise. Schema validation checks the structure and configuration values of a specification, but it cannot verify external resources, the existence of data fields, or expression behavior.