stat-summary

Per-axis reduction to a central value and an uncertainty band.

The output shape is controlled by axis:

• "y" — bucket rows by their raw x value and emit one (x, y, ymin, ymax) row per bucket.
• "x" — transpose: bucket rows by their raw y value and emit one (x, xmin, xmax, y) row per bucket.
• "both" (default) — when a grouping aesthetic is set with a continuous x (the data has been pre-partitioned upstream and bucketing would yield one row per observation), collapse the partition to a single bivariate row (x, y, xmin, xmax, ymin, ymax). Otherwise the per-x bucket path is used and xmin = xmax is set to the bucket’s parsed x whenever it is numeric, so horizontal-error geoms still find valid keys.

fun accepts a string name dispatched through summarise ("mean-se", "mean-cl-normal", "mean-cl-boot", "mean-sd", "median-hilow", "mean", "median", "quantile", "quantiles") or a Typst callable of the form (values, ..fun-args) -> (y, ymin, ymax).

Usage

stat-summary(
  fun: "mean-se",
  fun-args: (:),
  axis: "both",
)

Parameters

Parameter	Default	Description
fun	"mean-se"	Summary helper name or callable returning (y, ymin, ymax).
fun-args	(:)	Keyword arguments forwarded to the helper or callable, for example (multiplier: 2) for mean-se or (conf: 0.5) for median-hilow.
axis	"both"	Output axis: "both" (default), "x", or "y".

Returns

Statistic object with name: "summary", consumed by geom layers.

Outputs

• x.
• y.
• xmin.
• xmax.
• ymin.
• ymax.

Examples

Mean and standard-error summary per group, drawn as a line and ribbon stack.

#let d = ()
#for grp in ("a", "b", "c") {
  for i in range(20) {
    d.push((grp: grp, y: calc.sin(i) + i / 10))
  }
}
#plot(
  data: d,
  mapping: aes(x: "grp", y: "y"),
  layers: (
    geom-line(stat: stat-summary(fun: "mean-se")),
    geom-ribbon(stat: stat-summary(fun: "mean-se")),
  ),
  width: 10cm,
  height: 6cm,
)

stat: "summary" is equivalent to stat: stat-summary() with defaults (fun: "mean-se"). Use the constructor to choose a different reducer or pass fun-args.

#let d = ()
#for grp in ("a", "b", "c") {
  for i in range(20) {
    d.push((grp: grp, y: calc.sin(i) + i / 10))
  }
}
#plot(
  data: d,
  mapping: aes(x: "grp", y: "y"),
  layers: (
    geom-pointrange(
      size: 3pt,
      stat: stat-summary(fun: "median-hilow", fun-args: (conf: 0.5)),
    ),
  ),
  width: 10cm,
  height: 6cm,
)

See also

stat-summary-bin, stat-boxplot.