Skip to content

Global Config, Themes, and Styles

GenomeSpy supports visual defaults through config, built-in theme selection through theme, and reusable named buckets through config.style. The key idea is that configuration is hierarchical: it can be defined at the root, on nested views, and at import sites, which makes it practical for large visualizations composed of multiple panels, tracks, and reusable imported subtrees that each need their own local defaults while still fitting into a shared overall design.

Quick example

The example below configures quantitative axes to show grid lines, changes point defaults, and defines a reusable style bucket for the view background.

{
  "description": "Configuration overview example.",

  "view": {
    "style": "cell"
  },

  "config": {
    "point": {
      "filled": false,
      "size": 50
    },
    "axisQuantitative": {
      "grid": true
    },
    "style": {
      "cell": {
        "stroke": "#d0d0d0",
        "strokeWidth": 1
      }
    }
  },

  "data": { "url": "data/sincos.csv" },

  "mark": "point",

  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "sin", "type": "quantitative" }
  }
}

Properties

arrow
Type: ArrowConfig

Defaults for arrow marks.

axis
Type: AxisConfig

Defaults shared by all axes.

axisBottom
Type: AxisConfig

Defaults for bottom-oriented axes.

axisIndex
Type: AxisConfig

Defaults for axes that visualize GenomeSpy index scales.

axisLeft
Type: AxisConfig

Defaults for left-oriented axes.

axisLocus
Type: AxisConfig

Defaults for axes that visualize GenomeSpy locus scales.

axisNominal
Type: AxisConfig

Defaults for axes that visualize nominal data.

axisOrdinal
Type: AxisConfig

Defaults for axes that visualize ordinal data.

axisQuantitative
Type: AxisConfig

Defaults for axes that visualize quantitative data.

axisRight
Type: AxisConfig

Defaults for right-oriented axes.

axisTop
Type: AxisConfig

Defaults for top-oriented axes.

axisX
Type: AxisConfig

Defaults for x axes.

axisY
Type: AxisConfig

Defaults for y axes.

legend
Type: LegendConfig

Defaults shared by all legends. Set disable to true to suppress automatic legend creation by default.

legendTrack
Type: LegendConfig

Defaults for legends of track-like views that use index or locus scales on the x channel.

Default value: { "style": "track-bottom" }

link
Type: LinkConfig

Defaults for link marks.

mark
Type: MarkConfig

Defaults shared by all mark types.

point
Type: PointConfig

Defaults for point marks.

range
Type: RangeConfig

Named reusable ranges for channels such as shape, size, and color.

rect
Type: RectConfig

Defaults for rect marks.

rule
Type: RuleConfig

Defaults for rule marks.

scale
Type: ScaleConfig

Defaults for scale behavior and scale-type-specific buckets.

style
Type: object

Named reusable style buckets that marks, axes, legends, titles, and views can reference through their style properties.

text
Type: TextConfig

Defaults for text marks.

tick
Type: TickConfig

Defaults for tick marks.

title
Type: TitleConfig

Defaults for view titles.

view
Type: ViewConfig

Defaults for view background styling, including fill, stroke, shadow, and z-order properties.

Theme, Config, and Style

Use theme when you want a broad preset for the whole visualization. Use config when you want defaults for a scope. Use style when the same visual treatment should be referenced by name from marks, axes, titles, or views.

Named styles and resets

Named styles are defined under config.style and referenced with a style property. Style references add reusable defaults before the object that references them, so explicit properties still win.

Some guide config objects, such as axes and legends, can inherit styles from more general config buckets. Set style to null in a deeper scope to clear those inherited style defaults without clearing other inherited properties:

{
  "config": {
    "legendTrack": {
      "style": null
    }
  }
}

This is useful when a broad default style applies to most of a visualization but a subtree should keep the other defaults while using unstyled axes or legends.

Built-in themes

GenomeSpy currently supports these built-in themes:

  • genomespy
  • vegalite
  • quartz
  • dark
  • fivethirtyeight
  • urbaninstitute

The genomespy theme is the default GenomeSpy look. The vegalite theme follows Vega-Lite defaults where GenomeSpy supports the same features. The remaining themes are loosely adapted from vega-themes.

Theme selection is root-only. Specs can choose one of the built-in themes.

{
  "description": "Built-in FiveThirtyEight theme example.",

  "theme": "fivethirtyeight",

  "data": { "url": "data/sincos.csv" },

  "mark": "point",

  "encoding": {
    "x": { "field": "x", "type": "quantitative" },
    "y": { "field": "cos", "type": "quantitative" }
  }
}

Config scopes

Config can appear in the root spec, in any view, and at an import site. Scopes are merged from outermost to innermost, so the closest scope wins.

For imports, import-site config is merged before the imported spec's own root config. This allows imported tracks to stay self-contained while still fitting their host visualization.

Explicit local properties still override resolved defaults. For example, mark.color or encoding.x.axis.tickColor wins over inherited config.

Resolution order

The effective order is:

  1. internal defaults
  2. built-in default theme
  3. embed-level theme override
  4. root theme
  5. root config
  6. ancestor view config
  7. import-site config
  8. imported root config
  9. local view config
  10. explicit local properties

Mark defaults

Mark defaults come first from config.mark, then from a mark-type bucket such as config.point, config.rect, config.rule, or config.tick, and then from style buckets.

For example, config.style.point affects point marks even when mark.style is omitted.

Axis defaults

Axis defaults come from config.axis and then from more specific buckets such as config.axisX, config.axisTop, or config.axisQuantitative. Axis styles can be provided by config buckets and by explicit axis.style references in channel definitions. Set axis.style to null to clear inherited axis styles in a channel definition.

See also Axis.

Scale defaults

Scale defaults come from config.scale and config.range.

config.scale provides shared defaults and data-type-specific buckets such as nominal, ordinal, quantitative, index, and locus. Color scheme defaults can be configured with nominalColorScheme, ordinalColorScheme, and quantitativeColorScheme.

Named ranges such as "shape", "size", "angle", "heatmap", "ramp", and "diverging" are resolved through config.range.

GenomeSpy keeps positional scale ranges as an internal invariant, so explicit or configured positional range values are ignored.

See also Scale.

Title and view defaults

Title defaults come from config.title and from style buckets. If title.style is omitted, GenomeSpy applies the default "group-title" style name. GenomeSpy also provides built-in title styles such as "track-title" and "overlay-title" for common layout patterns.

See also Titles.

View background defaults come from config.view and from styles referenced by view.style. GenomeSpy also supports the implicit "cell" style model for view backgrounds.

View size defaults

config.view can define default sizes for views that do not specify width or height directly. These defaults follow Vega-Lite's continuous/discrete split:

continuousWidth
Type: number

The default width when the view has a continuous x scale.

Default value: "container"

discreteWidth
Type: number | Step

The default width when the view has a discrete x scale or no x scale. This may be a fixed width or a step size for each discrete domain value.

Default value: "container"

continuousHeight
Type: number

The default height when the view has a continuous y scale.

Default value: "container"

discreteHeight
Type: number | Step

The default height when the view has a discrete y scale or no y scale. This may be a fixed height or a step size for each discrete domain value.

Default value: "container"

step
Type: number | ExprRef

Default step size for discrete view sizes.

Default value: none

discreteWidth and discreteHeight can be fixed pixel values or step objects:

{
  "config": {
    "view": {
      "continuousWidth": 300,
      "continuousHeight": 300,
      "discreteWidth": { "step": 20 },
      "discreteHeight": { "step": 20 }
    }
  }
}

If these properties are omitted, GenomeSpy keeps its default "container" sizing behavior. See child sizing for details about "container" and other size shorthands.