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¶

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.

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, 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.

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 Vega-inspired themes are based on vegalite.

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:

internal defaults
built-in default theme
embed-level theme override
root theme
root config
ancestor view config
import-site config
imported root config
local view config
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.

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.

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.

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.

{
  "description": "Built-in title style examples.",

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

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

  "vconcat": [
    {
      "title": { "text": "Group title (the default)", "style": "group-title" },
      "padding": { "top": 18 },
      "mark": "point"
    },
    {
      "title": { "text": "Track title", "style": "track-title" },
      "padding": { "left": 65 },
      "mark": "point"
    },
    {
      "title": { "text": "Overlay title", "style": "overlay-title" },
      "mark": "point"
    },
    {
      "title": { "text": "Custom title", "style": "custom-title" },
      "padding": { "top": 28 },
      "mark": "point"
    }
  ],

  "config": {
    "style": {
      "custom-title": {
        "fontSize": 18,
        "fontWeight": "bold",
        "color": "#4a90e2"
      }
    },
    "view": { "stroke": "#d0d0d0", "strokeWidth": 1 }
  },

  "resolve": { "scale": { "x": "shared" }, "axis": { "x": "shared" } }
}