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": "A Palmer penguins scatter plot with a nominal species legend.",

  "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": "A Palmer penguins scatter plot with a quantitative body mass legend.",

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

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.

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

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 collected 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" }
        }
      }
    },
    {
      "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" }
        }
      }
    }
  ],

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

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.

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

Set legend to null on a channel to remove that channel's 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": "A Palmer penguins scatter plot with a checkbox for showing and hiding the legend.",

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

labelLimit

Type: number

Maximum label text width in pixels.

offset

Type: number

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

orient

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

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.

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.

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

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. Use config.legend to override those defaults globally, or a channel-level legend object to override a single legend.

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.

disable

Type: boolean | ExprRef

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

Default value: false

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

Type: number | "thin" | "light" | "regular" | "normal" | "medium" | "bold" | "black"

Legend label font weight.

labelLimit

Type: number

Maximum label text width in pixels.

labelOffset

Type: number

Offset between legend symbols and labels in pixels.

offset

Type: number

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

orient

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

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.

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

Type: number | "thin" | "light" | "regular" | "normal" | "medium" | "bold" | "black"

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.