geom-histogram

Histogram layer: bars of binned counts along the x aesthetic.

The layer runs stat-bin over the x column, then draws one bar per bin. Supply bins for a target bin count or binwidth to fix the width.

Usage

geom-histogram(
  mapping: none,
  data: none,
  bins: 30,
  binwidth: none,
  width: 1.0,
  colour: auto,
  fill: auto,
  stroke: none,
  alpha: auto,
  position: "stack",
  inherit-aes: true,
)

Parameters

Parameter Default Description
mapping none Layer-specific aesthetic mapping built with aes. Must map x.
data none Layer-specific dataset. Falls back to the plot data when none.
bins 30 Target number of bins when binwidth is none.
binwidth none Fixed bin width. Overrides bins when set.
width 1.0 Bar width as a fraction of the bin width (0 to 1).
colour auto Bar outline colour. auto resolves via the colour scale, falling back to the theme ink only when neither colour nor fill is set.
fill auto Bar fill colour. auto resolves via the fill scale or a neutral default.
stroke none Bar outline thickness (a Typst length) or stroke dictionary; none disables the outline.
alpha auto Bar opacity in [0, 1].
position "stack" Position adjustment. Defaults to "stack" so a fill/colour mapping yields stacked contributions per group.
inherit-aes true Whether to merge the plot-level mapping into this layer’s mapping.

Returns

Layer dictionary consumed by plot.

Examples

Twelve-bin partition, letting the layer pick bin width automatically.

#let d = range(0, 40).map(i => (
  x: calc.sin(i * 0.3) * 5 + i * 0.2,
))
#plot(
  data: d,
  mapping: aes(x: "x"),
  layers: (geom-histogram(bins: 12),),
  width: 10cm,
  height: 6cm,
)

Histogram of 40 noisy observations partitioned into 12 bins along x with bar heights showing per-bin counts.

Histogram of 40 noisy observations partitioned into 12 bins along x with bar heights showing per-bin counts.

Pin binwidth directly to align bin edges to integer boundaries.

#let d = range(0, 40).map(i => (
  x: calc.sin(i * 0.3) * 5 + i * 0.2,
))
#plot(
  data: d,
  mapping: aes(x: "x"),
  layers: (geom-histogram(binwidth: 1),),
  width: 10cm,
  height: 6cm,
)

Histogram of 40 noisy observations with fixed binwidth 1 along x aligning bin edges to integer boundaries.

Histogram of 40 noisy observations with fixed binwidth 1 along x aligning bin edges to integer boundaries.

Penguin body-mass distribution, stacked by species.

#plot(
  data: penguins,
  mapping: aes(x: "body-mass", fill: "species"),
  layers: (geom-histogram(binwidth: 250),),
  labs: labs(x: "Body Mass (g)", y: "Count", fill: "Species"),
  width: 11cm,
  height: 6cm,
)

Stacked histogram of penguin body mass (g) on the x axis with bins of width 250 g and species coloured by fill.

Stacked histogram of penguin body mass (g) on the x axis with bins of width 250 g and species coloured by fill.

See also

stat-bin, geom-bar, geom-col.

Back to top