Legend¶

Legends explain how visual channels such as color, fill, stroke, shape, size, and opacity map data values to visual values. GenomeSpy creates legends from encoding channels in the same spirit as Vega-Lite.

Symbol legends¶

Discrete encodings, such as nominal color, fill, stroke, and shape, create symbol legends. Quantitative encodings on symbol-like channels such as size, opacity, and strokeWidth show representative values.

{
  "description": [
    "Penguin scatterplot with species legend",
    "Uses a nominal species legend for a Palmer penguins scatterplot."
  ],

  "width": 250,
  "height": 250,

  "data": { "url": "vega-datasets/penguins.json" },

  "mark": { "type": "point", "filled": true, "size": 45, "opacity": 0.75 },

  "encoding": {
    "x": {
      "field": "Beak Length (mm)",
      "type": "quantitative",
      "scale": { "zero": false, "nice": true }
    },
    "y": {
      "field": "Beak Depth (mm)",
      "type": "quantitative",
      "scale": { "zero": false, "nice": true }
    },
    "color": {
      "field": "Species",
      "type": "nominal"
    }
  }
}

Gradient legends¶

Continuous quantitative color channels create gradient legends. The gradient uses the same scale as the plotted data.

{
  "description": [
    "Penguin scatterplot with body mass legend",
    "Uses a quantitative body mass legend for a Palmer penguins scatterplot."
  ],

  "width": 250,
  "height": 250,

  "data": { "url": "vega-datasets/penguins.json" },

  "mark": { "type": "point", "filled": true, "size": 45, "opacity": 0.75 },

  "encoding": {
    "x": {
      "field": "Beak Length (mm)",
      "type": "quantitative",
      "scale": { "zero": false, "nice": true }
    },
    "y": {
      "field": "Beak Depth (mm)",
      "type": "quantitative",
      "scale": { "zero": false, "nice": true }
    },
    "color": {
      "field": "Body Mass (g)",
      "type": "quantitative"
    }
  }
}

The ramp fills available space when its direction is parallel to its legend region. Otherwise it uses a natural length of 200 pixels. Set gradientLength for a fixed ramp. The other gradient properties adjust its appearance and desired tick density:

{
  "legend": {
    "gradientLength": 160,
    "gradientThickness": 16,
    "gradientOpacity": 0.8,
    "gradientStrokeColor": "#666",
    "gradientStrokeWidth": 1,
    "tickCount": 4
  }
}

Explicit values determine the ticks when provided and take precedence over tickCount.

Configuration¶

Legend properties are usually placed in the encoding channel that creates the legend:

{
  "encoding": {
    "color": {
      "field": "group",
      "type": "nominal",
      "legend": {
        "title": "Sample group"
      }
    }
  }
}

In composed views with shared legend resolution, view-level legends.<channel> can provide a shared location for the legend properties. See Resolution.

Placement¶

The orient property controls where the legend is placed. Side legends are placed outside the plot area. Corner legends are placed inside the plot area. It does not change how entries are arranged. Set direction to "horizontal" when horizontal entries are wanted.

Supported orientations:

left
right
top
bottom
top-left
top-right
bottom-left
bottom-right

Use side orientations for normal plot chrome. Use corner orientations when the legend should be placed over the data area. For inside legends, a translucent background improves readability.

{
  "legend": {
    "orient": "top-right",
    "backgroundFill": "white",
    "backgroundFillOpacity": 0.8,
    "padding": 4
  }
}

Multiple legends in a region¶

When several complete legends share an orientation, left and right regions stack them vertically by default. Top, bottom, and corner regions arrange them horizontally. Configure all regions or one orientation with config.legend.layout:

{
  "config": {
    "legend": {
      "layout": {
        "direction": "vertical",
        "top": { "direction": "horizontal" },
        "right": { "anchor": "middle" }
      }
    }
  }
}

Region layout is separate from legend.direction: region direction arranges complete legends, while legend.direction arranges entries within one legend. For external orientations, anchor positions the complete stack along the plot edge using "start" (the default), "middle", or "end". Corner legends remain anchored to their specified corner.

External regions wrap complete legends by default when their minimum sizes do not fit beside the plot. A horizontal region fills rows from left to right; a vertical region fills columns from top to bottom. Set wrap to false in the region layout to keep a single row or column. Inside-corner regions do not wrap.

Resolution¶

Legends participate in view resolution similarly to scales and axes. Use resolve.legend in composed views to choose whether child views share one legend or create independent legends.

When resolve.legend is not configured, legend resolution follows the corresponding scale resolution.

`shared` legend¶

{
  "resolve": {
    "scale": { "color": "shared" },
    "legend": { "color": "shared" }
  }
}

Shared legend resolution is most useful when sibling views encode the same field with a shared scale and should show a single legend.

{
  "description": "Palmer penguins scatter plots with a shared legend.",

  "data": { "url": "vega-datasets/penguins.json" },

  "resolve": {
    "scale": { "y": "independent", "color": "shared" },
    "legend": { "color": "shared" }
  },

  "hconcat": [
    {
      "title": "Beak shape",
      "mark": "point",
      "encoding": {
        "x": {
          "field": "Beak Length (mm)",
          "type": "quantitative"
        },
        "y": {
          "field": "Beak Depth (mm)",
          "type": "quantitative"
        },
        "color": {
          "field": "Species",
          "type": "nominal",
          "legend": { "orient": "bottom", "direction": "horizontal" }
        }
      }
    },
    {
      "title": "Body size",
      "mark": "point",
      "encoding": {
        "x": {
          "field": "Flipper Length (mm)",
          "type": "quantitative"
        },
        "y": {
          "field": "Body Mass (g)",
          "type": "quantitative"
        },
        "color": {
          "field": "Species",
          "type": "nominal",
          "legend": { "orient": "bottom", "direction": "horizontal" }
        }
      }
    }
  ],

  "config": {
    "legend": { "offset": 10 },
    "scale": { "quantitative": { "zero": false } },
    "point": { "filled": true, "size": 40, "opacity": 0.75 }
  }
}

For shared legend resolutions, legend properties can also be placed at the view level with legends.<channel>:

{
  "legends": {
    "color": {
      "title": "Sample group",
      "orient": "right"
    }
  },
  "layer": [
    ...
  ]
}

A view-level legend declaration must map to one legend resolution. If the subtree has multiple independent legends for the same channel, place the declaration closer to the intended subtree or use local encoding.<channel>.legend properties. Do not mix view-level legends.<channel> with participating channel-level legend properties for the same resolved legend.

When nested view-level legend declarations target the same resolution, the ancestor declaration shadows the whole descendant declaration; their properties are not merged. Declarations in separate sibling subtrees remain ambiguous and cause an error.

`collected` legends¶

Use "collected" to place complete descendant legends around a composition. This is useful in dense matrix-like layouts where legends beside every child would fragment the layout, but the underlying scales must remain distinct. Collection changes only layout. Legend resolution continues to follow the corresponding scale resolution:

Children with a shared scale produce one shared legend at the collector.
Children with independent scales produce separate legends at the collector.
Independent legends are not merged or deduplicated.

{
  "resolve": {
    "scale": { "color": "independent" },
    "legend": { "color": "collected" }
  }
}

The nearest ancestor that declares "collected" lays out the legends. Use "default": "collected" to collect every legend channel. Set a channel to "excluded" on a view or composition to keep that legend at its normal local or shared owner and prevent collection by outer ancestors.

{
  "description": "Collect independent legends around a composition",

  "resolve": {
    "scale": { "color": "independent" },
    "legend": { "color": "collected" }
  },

  "hconcat": [
    {
      "data": {
        "values": [
          { "x": "A", "group": "Control" },
          { "x": "B", "group": "Treatment" }
        ]
      },
      "mark": "rect",
      "encoding": {
        "x": { "field": "x", "type": "nominal", "axis": null },
        "color": {
          "field": "group",
          "type": "nominal",
          "legend": { "title": "Group" }
        }
      }
    },

    {
      "data": {
        "values": [
          { "x": "A", "score": 2 },
          { "x": "B", "score": 8 }
        ]
      },
      "mark": "rect",
      "encoding": {
        "x": { "field": "x", "type": "nominal", "axis": null },
        "color": {
          "field": "score",
          "type": "quantitative",
          "legend": { "title": "Score" }
        }
      }
    }
  ]
}

Titles¶

The legend title defaults to the channel title. Set title to override it, or to null to remove it. The title can be placed on any side of the legend body with titleOrient.

{
  "legend": {
    "title": "Sample group",
    "titleOrient": "left",
    "titlePadding": 3
  }
}

Disabling legends¶

Legends are created automatically for encodings that support them. Disable all automatic legends with config.legend.disable: true in the root specification.

Disable legends globally

{
  "config": {
    "legend": { "disable": true }
  }
}

Set legend to null on a channel to remove that channel's legend.

Remove one channel legend

{
  "encoding": {
    "color": {
      "field": "group",
      "type": "nominal",
      "legend": null
    }
  }
}

disable also accepts an expression reference. This is useful for parameterized specifications that let the user show or hide all legends without rebuilding the view.

{
  "description": [
    "Interactive legend visibility",
    "Uses a checkbox to show and hide the legend in a penguin scatterplot."
  ],

  "width": 250,
  "height": 250,

  "params": [
    {
      "name": "showLegends",
      "value": true,
      "bind": { "input": "checkbox", "name": "Show legends" }
    }
  ],

  "config": {
    "legend": {
      "disable": { "expr": "!showLegends" }
    }
  },

  "data": { "url": "vega-datasets/penguins.json" },

  "mark": { "type": "point", "filled": true, "size": 45, "opacity": 0.75 },

  "encoding": {
    "x": {
      "field": "Beak Length (mm)",
      "type": "quantitative",
      "scale": { "zero": false, "nice": true }
    },
    "y": {
      "field": "Beak Depth (mm)",
      "type": "quantitative",
      "scale": { "zero": false, "nice": true }
    },
    "color": {
      "field": "Species",
      "type": "nominal"
    }
  }
}

Properties¶

backgroundFill

Type: string

Fill color of the legend background.

backgroundFillOpacity

Type: number

Opacity of the legend background fill.

backgroundStroke

Type: string

Stroke color of the legend background.

backgroundStrokeOpacity

Type: number

Opacity of the legend background stroke.

backgroundStrokeWidth

Type: number

Stroke width of the legend background border.

columns

Type: number

The number of columns in which to arrange symbol legend entries.

direction

Type: "vertical" | "horizontal"

The direction in which legend entries are laid out. This is independent of orient, which selects the legend region.

Default value: "vertical"

gradientLength

Type: number

Fixed length of the gradient ramp in pixels. This is the width of a horizontal ramp and the height of a vertical ramp. When omitted, the ramp fills available space when its direction is parallel to its legend region. Otherwise its natural length is 200 pixels.

gradientOpacity

Type: number

Opacity of the gradient ramp.

Default value: 1

gradientStrokeColor

Type: string

Stroke color of the gradient ramp border.

gradientStrokeWidth

Type: number

Stroke width of the gradient ramp border in pixels.

Default value: 0

gradientThickness

Type: number

Thickness of the gradient ramp in pixels.

Default value: 12

labelLimit

Type: number

Maximum label text width in pixels.

offset

Type: number

External gap in pixels between the legend and the plot edge.

orient

The plot side or inside corner where the legend is placed. Side legends are placed outside the plot area. Corner legends are placed inside the plot area.

padding

Type: number

Internal padding in pixels around the legend content and background.

style

Type: string | string[] | null

Named style reference or references resolved from config.style. If an array is provided, later styles override earlier ones. Set to null to reset inherited legend styles.

symbolSize

Type: number

Symbol size in pixels squared.

symbolType

Type: string

Symbol shape.

tickCount

Type: number

Desired number of ticks for a quantitative gradient legend. Explicit values take precedence over this property.

Default value: 5

title

Type: string | null

Title text for the legend. If null, the title is removed.

titleOrient

Type: "top" | "bottom" | "left" | "right"

The side of the legend on which to place the title.

values

Type: array

Explicit values to show in the legend. For discrete symbol legends, the values define an ordered subset of entries. For quantitative symbol and gradient legends, the values define the shown representative values or ticks.

Styling¶

Legend defaults can be configured with config.legend. A channel-level legend object overrides the configured defaults for that legend.

{
  "config": {
    "legend": {
      "disable": false,
      "orient": "right",
      "offset": 12,
      "labelFontSize": 11,
      "titleFontSize": 12
    }
  }
}

Track-like legends¶

Named styles from config.style can also be referenced with legend.style. GenomeSpy includes a built-in track-bottom-legend style for compact track-like layouts. It places the title to the left of horizontally arranged entries.

{
  "legend": {
    "style": "track-bottom-legend"
  }
}

Views with an index or locus x scale use config.legendTrack as an intermediate default. These views usually form genome-browser-like horizontal tracks where there is more room below each track than to the side of a dense track stack. The default config.legendTrack style is therefore track-bottom-legend. Use config.legend to override those defaults globally, or a channel-level legend object to override a single legend. The old track-bottom name remains as a compatibility alias.

Clear this track-specific style at the root or in a subtree by setting config.legendTrack.style to null:

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

Config Properties¶

backgroundFill

Type: string

Fill color of the legend background.

backgroundFillOpacity

Type: number

Opacity of the legend background fill.

backgroundStroke

Type: string

Stroke color of the legend background.

backgroundStrokeOpacity

Type: number

Opacity of the legend background stroke.

backgroundStrokeWidth

Type: number

Stroke width of the legend background border.

columnPadding

Type: number

Padding between legend columns in pixels.

columns

Type: number

The number of columns in which to arrange symbol legend entries.

direction

Type: "vertical" | "horizontal"

The direction in which legend entries are laid out. This is independent of orient, which selects the legend region.

Default value: "vertical"

disable

Type: boolean | ExprRef

Disable automatic legend creation. Use legend: null on an encoding channel to remove that channel's legend.

Default value: false

gradientLength

Type: number

Fixed length of the gradient ramp in pixels. This is the width of a horizontal ramp and the height of a vertical ramp. When omitted, the ramp fills available space when its direction is parallel to its legend region. Otherwise its natural length is 200 pixels.

gradientOpacity

Type: number

Opacity of the gradient ramp.

Default value: 1

gradientStrokeColor

Type: string

Stroke color of the gradient ramp border.

gradientStrokeWidth

Type: number

Stroke width of the gradient ramp border in pixels.

Default value: 0

gradientThickness

Type: number

Thickness of the gradient ramp in pixels.

Default value: 12

labelAlign

Type: "left" | "center" | "right"

Horizontal alignment of legend labels.

labelBaseline

Type: "top" | "middle" | "bottom" | "alphabetic" | "baseline"

Baseline alignment of legend labels.

labelColor

Type: string

Legend label color.

labelFont

Type: string

Legend label font.

labelFontSize

Type: number

Legend label font size in pixels.

labelFontStyle

Type: "normal" | "italic"

Legend label font style.

labelFontWeight

Legend label font weight.

labelLimit

Type: number

Maximum label text width in pixels.

labelOffset

Type: number

Offset between legend symbols and labels in pixels.

layout

Type: LegendLayout

Layout of complete legends within each orientation region. A general direction or anchor applies to every region unless the orientation has its own override.

offset

Type: number

External gap in pixels between the legend and the plot edge.

orient

The plot side or inside corner where the legend is placed. Side legends are placed outside the plot area. Corner legends are placed inside the plot area.

padding

Type: number

Internal padding in pixels around the legend content and background.

rowPadding

Type: number

Padding between legend rows in pixels.

spacing

Type: number

Spacing in pixels between legends collected into the same legend region.

style

Type: string | string[] | null

Named style reference or references resolved from config.style. If an array is provided, later styles override earlier ones. Set to null to reset inherited legend styles.

symbolBaseFillColor

Type: string

Base fill color for legend symbols when the legend does not encode fill.

symbolBaseStrokeColor

Type: string

Base stroke color for legend symbols when the legend does not encode stroke.

symbolOffset

Type: number

Offset applied to legend symbols in pixels.

symbolSize

Type: number

Symbol size in pixels squared.

symbolStrokeWidth

Type: number

Legend symbol stroke width in pixels.

symbolType

Type: string

Symbol shape.

tickCount

Type: number

Desired number of ticks for a quantitative gradient legend. Explicit values take precedence over this property.

Default value: 5

title

Type: string | null

Title text for the legend. If null, the title is removed.

titleColor

Type: string

Legend title color.

titleFont

Type: string

Legend title font.

titleFontSize

Type: number

Legend title font size in pixels.

titleFontStyle

Type: "normal" | "italic"

Legend title font style.

titleFontWeight

Legend title font weight.

titleLimit

Type: number

Maximum title text width in pixels.

titleOrient

Type: "top" | "bottom" | "left" | "right"

The side of the legend on which to place the title.

titlePadding

Type: number

Padding in pixels between the legend title and the legend body.

values

Type: array

Explicit values to show in the legend. For discrete symbol legends, the values define an ordered subset of entries. For quantitative symbol and gradient legends, the values define the shown representative values or ticks.

Legend¶

Symbol legends¶

Gradient legends¶

Configuration¶

Placement¶

Multiple legends in a region¶

Resolution¶

shared legend¶

collected legends¶

Titles¶

Disabling legends¶

Properties¶

Styling¶

Track-like legends¶

Config Properties¶

`shared` legend¶

`collected` legends¶