labs

Build a label dictionary for the plot title, subtitle, caption, and axes.

Pass the result to plot as the labs argument. Axis names (x, y, colour, fill, …) override the corresponding scale name at render time, so legends and axis titles pick them up.

Usage

labs(
  title: none,
  subtitle: none,
  caption: none,
  tag: none,
  alt: none,
  x: none,
  y: none,
  colour: none,
  fill: none,
  size: none,
  alpha: none,
  linewidth: none,
  shape: none,
  linetype: none,
  stroke: none,
)

Parameters

Parameter	Default	Description
title	none	Plot title drawn above the panel.
subtitle	none	Smaller line drawn below the title.
caption	none	Caption line drawn below the panel.
tag	none	Optional tag (e.g., a figure number) drawn above the title.
alt	none	Alt text kept on the spec for accessibility tooling.
x	none	Title for the x axis.
y	none	Title for the y axis.
colour	none	Legend title for the colour aesthetic.
fill	none	Legend title for the fill aesthetic.
size	none	Legend title for the size aesthetic.
alpha	none	Legend title for the alpha aesthetic.
linewidth	none	Legend title for the linewidth aesthetic.
shape	none	Legend title for the shape aesthetic.
linetype	none	Legend title for the linetype aesthetic.
stroke	none	Legend title for the stroke aesthetic.

Returns

Dictionary tagged kind: "labs", consumed by plot.

Examples

Title block plus axis titles passed via labs.

#let d = (
  (x: 1, y: 2),
  (x: 2, y: 4),
  (x: 3, y: 3),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 3pt),),
  labs: labs(
    title: "Demo",
    subtitle: "A tiny dataset",
    caption: "Source: made up",
    x: "Index",
    y: "Value",
  ),
  width: 10cm,
  height: 6cm,
)

Setting an aesthetic name (colour) overrides the legend title; alt text is stored on the spec for accessibility tooling.

#let d = (
  (x: 1, y: 2, sp: "a"),
  (x: 2, y: 4, sp: "b"),
  (x: 3, y: 3, sp: "c"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", colour: "sp"),
  layers: (geom-point(size: 3pt),),
  labs: labs(
    title: "Coloured Groups",
    colour: "Species",
    alt: "Three points coloured by species",
  ),
  width: 10cm,
  height: 6cm,
)

Full label block on the penguins scatter: title, subtitle, caption, axis titles, and a legend title for the fill aesthetic.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", fill: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  labs: labs(
    title: "Penguin Body Mass Scales with Flipper Length",
    subtitle: "Three species across the Palmer Archipelago",
    caption: "Data: palmerpenguins (Horst, Hill & Gorman, 2020)",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    fill: "Species",
    alt: "Scatter of body mass against flipper length, coloured by species.",
  ),
  width: 12cm,
  height: 7cm,
)

See also

plot.