geom-smooth

Fitted trend line with an optional confidence ribbon.

Fits a smoother to (x, y) and draws the prediction as a line. When se is true, the pointwise band is drawn underneath the line.

Usage

geom-smooth(
  mapping: none,
  data: none,
  method: "lm",
  se: true,
  level: 0.95,
  stroke: 1pt,
  colour: auto,
  fill: auto,
  alpha: auto,
  linetype: auto,
  inherit-aes: true,
)

Parameters

Parameter Default Description
mapping none Layer-specific aesthetic mapping built with aes. Falls back to the plot mapping when none.
data none Layer-specific dataset. Falls back to the plot data when none.
method "lm" Smoother method. "lm" is the only supported value in v1.
se true Whether to draw the confidence ribbon around the fit.
level 0.95 Confidence level for the ribbon (e.g., 0.95).
stroke 1pt Line thickness (a Typst length).
colour auto Fixed line colour. auto picks a neutral default.
fill auto Fixed ribbon fill. auto reuses the line colour.
alpha auto Ribbon opacity in [0, 1].
linetype auto Dash keyword for the fitted line. auto resolves via the linetype scale or defaults to "solid".
inherit-aes true Whether to merge the plot-level mapping into this layer’s mapping.

Returns

Layer dictionary consumed by plot.

Examples

Linear fit through points with the default 95% confidence band.

#let d = range(0, 20).map(i => (
  x: i,
  y: i * 0.5 + calc.sin(i * 0.4) * 2,
))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (
    geom-point(size: 2pt),
    geom-smooth(method: "lm"),
  ),
  width: 10cm,
  height: 6cm,
)

Scatter of 20 noisy linear points with a linear-model fit line and a translucent 95% confidence ribbon around it.

Scatter of 20 noisy linear points with a linear-model fit line and a translucent 95% confidence ribbon around it.

Disable the ribbon with se: false for a cleaner trend overlay.

#let d = range(0, 20).map(i => (
  x: i,
  y: i * 0.5 + calc.sin(i * 0.4) * 2,
))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (
    geom-point(size: 2pt),
    geom-smooth(method: "lm", se: false, stroke: 1.4pt),
  ),
  width: 10cm,
  height: 6cm,
)

Scatter of 20 noisy linear points overlaid with a thicker linear-model fit line and no confidence ribbon.

Scatter of 20 noisy linear points overlaid with a thicker linear-model fit line and no confidence ribbon.

Per-species linear fits on the penguins data: mapping colour splits the smoother into one trend per group.

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
    fill: "species",
  ),
  layers: (
    geom-point(size: 2pt, alpha: 0.6),
    geom-smooth(method: "lm", alpha: 0.2),
  ),
  labs: labs(
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
    colour: "Species",
    fill: "Species",
  ),
  width: 11cm,
  height: 6cm,
)

Penguin scatter of flipper length against body mass with per-species linear fits and translucent confidence ribbons.

Penguin scatter of flipper length against body mass with per-species linear fits and translucent confidence ribbons.

See also

stat-smooth, geom-line, geom-ribbon.

Back to top