Visualization Grammar¶

GenomeSpy Core uses a declarative visualization grammar, not a set of predefined chart templates. Its JSON specifications describe which data to use, how to display it, and how views fit together. This lets you create genome tracks and other views tailored to your data without writing drawing commands. If you work in Python, GenomeSpy for Python builds the same specifications from Python chart definitions.

The grammar combines data sources, transformations, marks, scales, axes, titles, and legends. Data consists of rows with named fields. Transformations filter, derive, or summarize rows before encodings map fields, values, and expressions to visual channels. Scales translate data values into visual values, marks render the results, and axes and legends describe the scales.

A grammar based on Vega-Lite

GenomeSpy's visualization grammar is based on Vega-Lite and follows its concepts and syntax where practical, providing partial specification compatibility. The implementation is independent and designed for visualizing and analyzing large datasets containing genomic coordinates. This documentation links to the Vega-Lite documentation where the same grammar concepts apply.

The grammar-of-graphics approach was introduced in The Grammar of Graphics and developed further in ggplot2 and Vega-Lite.

Unit views¶

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

{
  "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" }
  }
}

View hierarchy and composition¶

The root of a specification can be a unit view or a composition view. It can also define settings for the whole specification, including genome assemblies, themes and configuration, the background, and the base URL for external resources.

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.

Parameters and interaction¶

Parameters add values, input controls, and interactive selections to a specification. Expressions can derive values from parameters and drive mark properties, while conditional encodings and transformations can respond to parameter values and selections. This allows interaction to change visual properties and data while preserving the declarative specification model.

Schema-assisted editing¶

Misspelled properties, invalid values, and settings in the wrong place are easy to overlook in a specification. A JSON-aware editor can catch many of these errors as you type. It can also suggest available properties and show their documentation.

A schema is a machine-readable description of the properties and values that a specification accepts. Enable these editor features by adding $schema to the root of a Core specification:

{
  "$schema": "https://genomespy.app/schema/core/v1.json",
  "data": { "url": "data/example.csv" },
  "mark": "point",
  "encoding": {}
}

Major-version URLs are recommended because they follow compatible releases. Minor (v1.2.json) and exact (v1.2.3.json) URLs are available when tighter reproducibility is needed. Update the URL when upgrading to a new major version. Schemas are also available from jsDelivr and unpkg.

GenomeSpy App specifications use a different schema; see Visualizing Sample Collections.

VS Code supports JSON schemas without an extension. Its JSON documentation also explains how to associate schemas through workspace or user settings.

The Playground selects the Core schema automatically, and inline documentation examples omit $schema. Schema validation cannot verify external resources, data fields, or expression behavior.

Unit view reference¶

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. When a positional scale is declared at the view level, an axis can be created explicitly by declaring the corresponding channel here.

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.

predicates

Type: object

Define a selection test once instead of repeating it across this unit's conditional encodings, including conditional draw order. Use test: { ref: "name" } in a condition to reference it.

Definitions are local to this unit and are not inherited. An inherited encoding may reference a name if each consuming unit defines it. Selection parameters and projected channels resolve in this unit. Filter transforms do not use these definitions.

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. A scale declaration does not create an axis; declare the corresponding axes property when an axis is needed without a positional encoding.

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