Facets, coordinates, and composition

Split data into small multiples, transform coordinates, and compose panels.

Small multiples are the strongest answer to overplotting: one panel per group, shared axes, and the eye does the comparison. facet-wrap and facet-grid handle the splitting, with free scales when panels span very different ranges; keep scales shared whenever the comparison is the point. Coordinate systems clip, fix, flip, or transform the panel itself, and compose arranges several plots with shared legends. Every example ships its full source: click View source to copy it.

Feature demos

two categoricals pie chart

One pie per level under facet-wrap. A radial panel rings its tick labels inside its own circle rather than on a shared edge, so every panel keeps them; the angular labels follow the sweep, which coord-radial(theta: "y") puts on y.

three or more variables small multiples

One panel per level of a discrete variable via facet-wrap.

three or more variables small multiples

Panels laid out on a row × column grid with facet-grid.

three or more variables small multiples

Pass scales: "free" to facet-grid so x is freed per column and y per row.

time series small multiples

Pass scales: "free_y" to facet-wrap so each panel trains its own y range.

three or more variables small multiples

Pass scales: "free" to facet-wrap to train both axes per panel.

three or more variables small multiples

label-both prefixes each strip with the facet variable name (e.g., cyl: 4).

three or more variables small multiples

geom-smooth inside facet-wrap fits each panel only on its own subset.

Cartesian zoom

two numerics

coord-cartesian clips the view via xlim and ylim without dropping data.

Fixed aspect ratio

two numerics

coord-fixed locks one x unit equal to ratio y units regardless of panel size.

two numerics

coord-fixed applies inside every facet-wrap panel.

Coordinate-level transforms

two numerics

coord-transform warps the displayed coordinates without setting transform on each scale; overrides any scale-level transform.

Composed panels with shared legends

three or more variables composed panels

compose arranges several deferred plots and hoists legends shared across panels via collect, with guides(default: guide-legend(position: ...)) controlling where the merged legend sits.

// A faceted coord-radial plot keeps its tick labels on every panel: the
// labels ring the inside of each circle rather than sitting on a shared edge,
// so a panel with none would have no scale to read against. The angular
// labels follow the sweep, `y` under coord-radial(theta: "y").

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let quarters = (
  (slice: "all", value: 5, part: "Direct", quarter: "Q1"),
  (slice: "all", value: 3, part: "Partner", quarter: "Q1"),
  (slice: "all", value: 4, part: "Direct", quarter: "Q2"),
  (slice: "all", value: 4, part: "Partner", quarter: "Q2"),
  (slice: "all", value: 6, part: "Direct", quarter: "Q3"),
  (slice: "all", value: 2, part: "Partner", quarter: "Q3"),
  (slice: "all", value: 3, part: "Direct", quarter: "Q4"),
  (slice: "all", value: 5, part: "Partner", quarter: "Q4"),
)

#plot(
  data: quarters,
  mapping: aes(x: "slice", y: "value", fill: "part"),
  layers: (geom-col(width: 1, position: "stack"),),
  coord: coord-radial(theta: "y"),
  scales: scales(y: scale-continuous(expand: false)),
  facet: facet-wrap("quarter", ncolumn: 2),
  labels: labels(title: "Revenue Split by Quarter", fill: "Channel"),
  theme: theme-minimal(),
  width: 12cm,
  height: 10cm,
)

// facet-wrap: one panel per level of a discrete variable.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#plot(
  data: mpg,
  mapping: aes(x: "displ", y: "hwy", colour: "class"),
  layers: (geom-point(size: 2.5pt, alpha: 0.85),),
  facet: facet-wrap("cyl", ncolumn: 3),
  guides: guides(colour: none),
  labels: labels(
    title: "Highway Fuel Economy by Cylinder Count",
    x: "Displacement (L)",
    y: "Highway mpg",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// facet-grid: panels arranged on a row × column grid of two discrete variables.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
  layers: (geom-point(size: 2pt, alpha: 0.85),),
  facet: facet-grid(rows: "sex", columns: "species", labeller: label-both()),
  scales: scales(y: scale-continuous(labels: format-comma())),
  guides: guides(colour: none),
  labels: labels(
    title: "Penguin Morphology by Sex and Species",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// facet-grid with free scales: x is free per column, y is free per row.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

// Each species (column) lives on a distinct x range; each sex (row) on a
// distinct y range, so shared scales would crush most panels to a corner.
#let d = ()
#for (sp, x0) in (("a", 0), ("b", 100)) {
  for (sex, y0) in (("F", 0), ("M", 1000)) {
    for i in range(0, 6) {
      d.push((sp: sp, sex: sex, x: x0 + i, y: y0 + i * 2))
    }
  }
}

#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 2pt),),
  facet: facet-grid(rows: "sex", columns: "sp", scales: "free"),
  labels: labels(x: "x", y: "y"),
  width: 12cm,
  height: 8cm,
)

// Facet wrap with free y: each panel trains its own y axis on its own subset.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let series = ()
#for x in range(0, 12) {
  series.push((scale: "millis", x: x, y: 0.1 * x + 0.05))
  series.push((scale: "seconds", x: x, y: 2.0 * x + 1.0))
  series.push((scale: "minutes", x: x, y: 50.0 * x + 5.0))
}

#plot(
  data: series,
  mapping: aes(x: "x", y: "y"),
  layers: (
    geom-line(stroke: 1.2pt, colour: rgb("#1f77b4")),
    geom-point(size: 2pt),
  ),
  facet: facet-wrap("scale", ncolumn: 3, scales: "free_y"),
  labels: labels(
    title: "Per-panel y axis with scales = free_y",
    subtitle: "Each panel trains its own y range so disparate magnitudes read clearly",
    x: "Step",
    y: "Value",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// Facet wrap with both axes free: each panel trains its own x and y range.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let zooms = (
  (scale: "near (0-3)", t: 0, v: 1.2),
  (scale: "near (0-3)", t: 1, v: 1.4),
  (scale: "near (0-3)", t: 2, v: 1.5),
  (scale: "near (0-3)", t: 3, v: 1.6),
  (scale: "mid (50-80)", t: 50, v: 30),
  (scale: "mid (50-80)", t: 60, v: 38),
  (scale: "mid (50-80)", t: 70, v: 45),
  (scale: "mid (50-80)", t: 80, v: 52),
  (scale: "far (1000-2500)", t: 1000, v: 600),
  (scale: "far (1000-2500)", t: 1500, v: 720),
  (scale: "far (1000-2500)", t: 2000, v: 880),
  (scale: "far (1000-2500)", t: 2500, v: 950),
)

#plot(
  data: zooms,
  mapping: aes(x: "t", y: "v"),
  layers: (
    geom-line(stroke: 1.2pt, colour: rgb("#1f77b4")),
    geom-point(size: 2.5pt),
  ),
  facet: facet-wrap("scale", ncolumn: 3, scales: "free"),
  labels: labels(
    title: "scales = free trains both x and y per panel",
    subtitle: "Useful when groups span very different domains in both directions",
    x: "Time",
    y: "Value",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// Facet labellers: strip text driven by label-both() prefixes the variable name.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#plot(
  data: mpg,
  mapping: aes(x: "displ", y: "hwy", colour: "class"),
  layers: (geom-point(size: 2.5pt, alpha: 0.85),),
  facet: facet-wrap("cyl", ncolumn: 3, labeller: label-both()),
  guides: guides(colour: none),
  labels: labels(
    title: "Highway mpg per Cylinder Count",
    subtitle: "label-both() prefixes each strip with the facet variable name",
    x: "Displacement (L)",
    y: "Highway mpg",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// Facet-wrap with a per-panel smoother fitted only on each panel's subset.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let accent = rgb("#1f77b4")

#plot(
  data: mpg,
  mapping: aes(x: "displ", y: "hwy"),
  layers: (
    geom-point(size: 2.5pt, alpha: 0.85, colour: accent),
    geom-smooth(method: "lm", colour: accent, fill: accent, alpha: 0.2),
  ),
  facet: facet-wrap("cyl", ncolumn: 3, labeller: label-both()),
  labels: labels(
    title: "Per-Panel Linear Smoother",
    subtitle: "Each fit follows only the rows in its own panel",
    x: "Displacement (L)",
    y: "Highway mpg",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// coord-cartesian: zoom in via x-limits/y-limits without dropping rows.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let accent = rgb("#1f77b4")
#let df = range(0, 25).map(i => (x: i, y: i * i))

#plot(
  data: df,
  mapping: aes(x: "x", y: "y"),
  layers: (
    geom-line(stroke: 1pt, colour: accent),
    geom-point(size: 2pt, fill: accent),
  ),
  coord: coord-cartesian(x-limits: (5, 15), y-limits: (0, 250)),
  labels: labels(
    title: "Coord-Cartesian Zoom",
    subtitle: "x-limits and y-limits clip the view; rows outside the window stay in the data",
    x: "X",
    y: "Y",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// coord-fixed locks the panel so one x unit equals `ratio` y units.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let accent = rgb("#1f77b4")
#let df = range(0, 11).map(i => (x: i, y: i))

#let panel(title, coord-arg) = plot(
  data: df,
  mapping: aes(x: "x", y: "y"),
  layers: (
    geom-line(stroke: 1pt, colour: accent),
    geom-point(size: 2pt, fill: accent),
  ),
  coord: coord-arg,
  labels: labels(title: title, x: "X", y: "Y"),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

#grid(
  columns: 1,
  row-gutter: 0.5cm,
  panel("Default cartesian (panel ratio)", none),
  panel("coord-fixed(ratio: 1) — square units", coord-fixed(ratio: 1)),
)

// coord-fixed combined with facet-wrap: every panel keeps a 1:1 unit ratio.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let accent = rgb("#1f77b4")

#let lines = ()
#for x in range(0, 11) {
  lines.push((line: "y = x", x: x, y: x))
  lines.push((line: "y = x + 1", x: x, y: x + 1))
  lines.push((line: "y = x − 1", x: x, y: x - 1))
}

#plot(
  data: lines,
  mapping: aes(x: "x", y: "y"),
  layers: (
    geom-line(stroke: 1pt, colour: accent),
    geom-point(size: 2pt, fill: accent),
  ),
  facet: facet-wrap("line", ncolumn: 3),
  coord: coord-fixed(ratio: 1),
  labels: labels(
    title: "Coord-Fixed Inside Facet-Wrap",
    subtitle: "Every panel locks the same 1:1 ratio",
    x: "X",
    y: "Y",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// coord-transform: warp the displayed coordinates without setting transform
// on each scale. Equivalent to scale-continuous(transform: ...) in the
// current implementation; provided as a coord-level entry point.

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let d = (
  (x: 1, y: 1),
  (x: 3, y: 5),
  (x: 10, y: 25),
  (x: 30, y: 100),
  (x: 100, y: 500),
  (x: 300, y: 2500),
  (x: 1000, y: 10000),
)

#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-line(stroke: 0.6pt, alpha: 0.4), geom-point(size: 3pt)),
  coord: coord-transform(x: "log10", y: "log10"),
  guides: guides(x: guide-axis-logticks(), y: guide-axis-logticks()),
  labels: labels(title: "coord-transform(x: \"log10\", y: \"log10\")"),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// Mixing with scale-level transform: coord-transform overrides the scale's
// transform so the final visual reflects the coord setting.
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 3pt),),
  scales: scales(y: scale-continuous(transform: "sqrt")),
  coord: coord-transform(x: "log10"),
  labels: labels(title: "Scale-Y Sqrt + Coord-Transform X log10"),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

#import "@preview/gribouille:0.7.0": *

#set page(width: auto, height: auto, margin: 0cm)

#let mtcars = (
  (mpg: 21.0, wt: 2.620, hp: 110, cyl: "6"),
  (mpg: 22.8, wt: 2.320, hp: 93, cyl: "4"),
  (mpg: 18.7, wt: 3.440, hp: 175, cyl: "8"),
  (mpg: 16.4, wt: 4.070, hp: 205, cyl: "8"),
  (mpg: 33.9, wt: 1.835, hp: 113, cyl: "4"),
  (mpg: 21.4, wt: 3.215, hp: 110, cyl: "6"),
)

#let panel(mapping) = defer(
  plot,
  data: mtcars,
  mapping: mapping,
  layers: (geom-point(),),
)

// Gallery showcase: a single squared two-by-two composition with a shared
// colour legend, panel tags, and a composition title. The full set of
// `collect` / legend-placement / `labels` / stack variations lives in the
// typstdoc `@examples` on the reference page.
#compose(
  panel(aes(x: "wt", y: "mpg", colour: as-factor("cyl"))),
  panel(aes(x: "hp", y: "mpg", colour: as-factor("cyl"))),
  panel(aes(x: "wt", y: "hp", colour: as-factor("cyl"))),
  panel(aes(x: "hp", y: "wt", colour: as-factor("cyl"))),
  columns: 2,
  tag-levels: "A",
  tag-prefix: "(",
  tag-suffix: ")",
  labels: labels(title: "Motor Trend road tests", caption: "Source: mtcars"),
  width: 13cm,
  height: 10cm,
)