Uncertainty and error

Show intervals, ranges, and confidence around estimates.

An estimate without its uncertainty overstates what you know; these charts put the interval on the page. Point-plus-interval geoms beat “dynamite” bars because they show the range without implying a bar’s zero baseline, and ribbons carry intervals along a continuous axis. Always say what the interval is (standard error, 95% confidence, prediction quantiles) in the caption; an unlabelled band is decoration. Every example ships its full source: click View source to copy it.

Showcase

Intervals over dynamite bars

numeric vs categorical point ranges

geom-pointrange with a normal-theory 95% CI from stat-summary: the compact, midsize, and subcompact intervals overlap, so the ranking those three means suggest does not survive the uncertainty.

Fan chart

time series

Graded 50/80/95% ribbons layered with geom-ribbon around a dashed extrapolation, each band labelled in-plot so the shading is never decoration.

A band that explains itself

two numerics scatter with trend line

geom-smooth with its 95% confidence band, and a caption saying exactly what the band covers; an unlabelled band is decoration.

Feature demos

Ribbon bounds

time series line with ribbon

Explicit ymin / ymax aesthetics drive geom-ribbon around a fitted line.

Mean ± SE summary

numeric vs categorical mean and error bars

Per-x summary statistic via stat-summary, layered over the raw points.

Errorbar geom family

numeric vs categorical error bars

Side-by-side comparison of geom-errorbar, geom-linerange, geom-crossbar, and geom-pointrange.

Horizontal error bars

numeric vs categorical forest plot

Per-category horizontal ranges via geom-errorbarh with point estimates.

// Showcase: mean highway economy with 95% confidence intervals as
// point-ranges; intervals over "dynamite" bars, and the caption says what
// the range is.

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

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

#let accent = okabe-ito.at(5)

#plot(
  data: mpg,
  mapping: aes(x: "class", y: "hwy"),
  layers: (
    geom-jitter(
      size: 2pt,
      alpha: 0.25,
      colour: accent,
      position: position-jitter(width: 0.1, seed: 42),
    ),
    geom-pointrange(
      stat: stat-summary(fun: "mean-cl-normal"),
      size: 3.5pt,
      stroke: 1.2pt,
      colour: accent,
      fill: accent,
    ),
  ),
  labels: labels(
    title: "Compact, midsize, and subcompact cannot be told apart",
    subtitle: "Mean highway mpg per vehicle class with 95% confidence intervals",
    x: none,
    y: "Highway mpg",
    caption: "Interval: normal-theory 95% CI of the mean; classes with a single observation carry no interval. Source: bundled mpg dataset.",
  ),
  theme: theme-minimal(axis-ticks-x: element-tick(length: 0.12cm)),
  width: 12cm,
  height: 8cm,
)

// Showcase: fan chart with graded 50/80/95% ribbons around a forecast;
// each band is labelled in-plot so the reader knows what the shading means.

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

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

#let accent = okabe-ito.at(5)

// Twelve observed months, then a six-month linear extrapolation whose
// uncertainty widens with the horizon.
#let observed = (
  (8.4, 8.9, 9.6, 10.1, 10.7, 11.6, 12.1, 12.6, 13.1, 13.9, 14.3, 14.7)
    .enumerate()
    .map(pair => (month: pair.at(0) + 1, value: pair.at(1)))
)

// Two-sided band multipliers, derived rather than pasted: a 50% band spans
// the central half of the normal, so its edge is the 75th percentile.
#let z50 = qnorm(0.75)
#let z80 = qnorm(0.90)
#let z95 = qnorm(0.975)

#let last = observed.last()
#let slope = 0.42
#let forecast = range(0, 7).map(step => {
  let spread = 0.35 * step
  let fit = last.value + slope * step
  (
    month: last.month + step,
    fit: fit,
    lo50: fit - z50 * spread,
    hi50: fit + z50 * spread,
    lo80: fit - z80 * spread,
    hi80: fit + z80 * spread,
    lo95: fit - z95 * spread,
    hi95: fit + z95 * spread,
  )
})

#plot(
  data: observed,
  mapping: aes(x: "month", y: "value"),
  layers: (
    geom-ribbon(
      inherit-aes: false,
      data: forecast,
      mapping: aes(x: "month", ymin: "lo95", ymax: "hi95"),
      fill: accent,
      alpha: 0.15,
    ),
    geom-ribbon(
      inherit-aes: false,
      data: forecast,
      mapping: aes(x: "month", ymin: "lo80", ymax: "hi80"),
      fill: accent,
      alpha: 0.25,
    ),
    geom-ribbon(
      inherit-aes: false,
      data: forecast,
      mapping: aes(x: "month", ymin: "lo50", ymax: "hi50"),
      fill: accent,
      alpha: 0.4,
    ),
    geom-line(stroke: 1.4pt, colour: accent),
    geom-line(
      inherit-aes: false,
      data: forecast,
      mapping: aes(x: "month", y: "fit"),
      stroke: 1.2pt,
      colour: accent,
      linetype: (4pt, 3pt),
    ),
    annotate(
      "text",
      x: 18.2,
      y: 18.6,
      label: "50%",
      size: 8pt,
      anchor: "west",
      colour: accent,
    ),
    annotate(
      "text",
      x: 18.2,
      y: 19.9,
      label: "80%",
      size: 8pt,
      anchor: "west",
      colour: accent,
    ),
    annotate(
      "text",
      x: 18.2,
      y: 21.3,
      label: "95%",
      size: 8pt,
      anchor: "west",
      colour: accent,
    ),
  ),
  scales: scales(x: scale-continuous(limits: (1, 20))),
  labels: labels(
    title: "The forecast is a range, not a line",
    subtitle: "Observed values (solid), extrapolation (dashed), and 50/80/95% prediction bands",
    x: "Month",
    y: "Index",
    caption: "Synthetic series; band multipliers from the normal quantiles.",
  ),
  theme: theme-minimal(),
  width: 13cm,
  height: 8cm,
)

// Showcase: a smoother whose confidence band is explained where it is read;
// the caption states exactly what the shading means.

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

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

#let accent = okabe-ito.at(5)

#plot(
  data: mpg,
  mapping: aes(x: "displ", y: "hwy"),
  layers: (
    geom-point(size: 2.2pt, alpha: 0.45, fill: accent),
    geom-smooth(
      method: "lm",
      se: true,
      level: 0.95,
      colour: accent,
      fill: accent,
      alpha: 0.2,
    ),
  ),
  labels: labels(
    title: "Each added litre of displacement costs about 3.8 highway mpg",
    subtitle: "Linear fit with its 95% confidence band",
    x: "Engine displacement (litres)",
    y: "Highway mpg",
    caption: "The band covers the mean response with 95% confidence; single vehicles vary more widely. Source: bundled mpg dataset.",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 8cm,
)

// Ribbon + line: explicit ymin/ymax bounds around a fitted trend.

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

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

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

#let df = ()
#for i in range(0, 20) {
  let mid = i * 0.5 + 1
  df.push((t: i, y: mid, lo: mid - 1.2, hi: mid + 1.2))
}

#plot(
  data: df,
  mapping: aes(x: "t", y: "y", ymin: "lo", ymax: "hi"),
  layers: (
    geom-ribbon(fill: accent, alpha: 0.3),
    geom-line(colour: accent, stroke: 1.2pt),
    geom-point(size: 2.5pt, fill: accent),
  ),
  scales: scales(x: scale-continuous(name: "Time step"), y: scale-continuous(name: "Value")),
  labels: labels(
    title: "Trend with an Explicit Ribbon Band",
    subtitle: "ymin and ymax aesthetics drive geom-ribbon directly",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// stat-summary collapses each x bucket to a summary statistic per layer.

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

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

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

#plot(
  data: mpg,
  mapping: aes(x: as-factor("cyl"), y: "hwy"),
  layers: (
    geom-jitter(
      size: 2pt,
      alpha: 0.4,
      colour: accent,
      position: position-jitter(width: 0.12),
    ),
    geom-errorbar(
      stat: stat-summary(fun: "mean-se", fun-args: (multiplier: 1)),
      width: 0.25,
      stroke: 1pt,
      colour: accent,
    ),
    geom-point(
      stat: stat-summary(fun: "mean-se", fun-args: (multiplier: 1)),
      size: 3.5pt,
      fill: accent,
    ),
  ),
  labels: labels(
    title: "Highway Fuel Economy by Cylinder Count",
    subtitle: "Mean ± 1 SE on top of the raw jittered observations",
    x: "Cylinders",
    y: "Highway mpg",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

// Errorbar family: four range-style geoms over the same per-quarter summary.

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

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

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

#let revenue = (
  (quarter: 1, mean: 12.4, lo: 11.0, hi: 13.5),
  (quarter: 2, mean: 14.1, lo: 13.0, hi: 15.4),
  (quarter: 3, mean: 13.6, lo: 12.0, hi: 14.8),
  (quarter: 4, mean: 16.2, lo: 14.6, hi: 17.7),
)

#let panel(title, layers) = plot(
  data: revenue,
  mapping: aes(x: "quarter", y: "mean", ymin: "lo", ymax: "hi"),
  layers: layers,
  scales: scales(x: scale-continuous(breaks: (1, 2, 3, 4)), y: scale-continuous(labels: format-currency(symbol: "$", digits: 1))),
  labels: labels(title: title, x: "Quarter", y: "Revenue"),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

#grid(
  columns: 1,
  row-gutter: 0.5cm,
  panel("geom-errorbar", (
    geom-errorbar(width: 0.4, stroke: 1pt, colour: accent),
    geom-point(size: 3pt, fill: accent),
  )),
  panel("geom-linerange", (
    geom-linerange(stroke: 1.2pt, colour: accent),
    geom-point(size: 3pt, fill: accent),
  )),
  panel("geom-crossbar", (
    geom-crossbar(fill: rgb("#a8c6d8"), stroke: 1pt, colour: accent),
  )),
  panel("geom-pointrange", (
    geom-pointrange(size: 3pt, stroke: 1.2pt, colour: accent),
  )),
)

// geom-errorbarh: horizontal error bars per category, plus point estimates.

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

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

#let summary = (
  (class: "compact", mean: 28.7, lo: 26.4, hi: 31.0),
  (class: "midsize", mean: 27.2, lo: 24.6, hi: 29.8),
  (class: "subcompact", mean: 28.1, lo: 25.0, hi: 31.2),
  (class: "suv", mean: 18.1, lo: 15.4, hi: 20.8),
  (class: "pickup", mean: 16.9, lo: 14.5, hi: 19.3),
  (class: "minivan", mean: 22.2, lo: 19.7, hi: 24.7),
  (class: "2seater", mean: 24.8, lo: 22.0, hi: 27.6),
)

#plot(
  data: summary,
  mapping: aes(y: "class", x: "mean", xmin: "lo", xmax: "hi"),
  layers: (
    geom-errorbarh(height: 0.35, stroke: 1.2pt, colour: rgb("#1f77b4")),
    geom-point(size: 3.5pt, fill: rgb("#1f77b4")),
  ),
  labels: labels(
    title: "Highway Fuel Economy by Vehicle Class",
    subtitle: "Horizontal error bars span the 95% confidence interval around each mean",
    x: "Highway mpg",
    y: "Class",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)