Skip to content

Show distributions

hist(), box(), violin(), density() and errorbar() summarise each panel's rows in Python, and draw the result as bars, boxes, violins, lines and error bars. Their bins and x values are the same in every panel, so the panels compare. Brushing selects whole bins, boxes, violins and error bars, and selected() gives the rows they stand for.

Histograms

from anytrellis import Trellis
from anytrellis.datasets import load

penguins = load("penguins")
plot = Trellis(penguins, wrap="species", cols=3, panel_height=170)
plot.hist(x="flipper_length_mm", binwidth=2, color="sex")
plot
Argument Sets
bins=30 the number of bins over the values' range, or a list of edges
binwidth=2 a bin width instead, the edges at its multiples (times: "7D", "6h")
stat="count" "percent" of each panel's rows, or "density" (an area of 1 per panel)
position="stack" with a colour: stacked; "fill", as shares of each bin (up to 100%); or "identity" (overlapping)

stat="percent" compares the shape of panels with very different numbers of rows. A category column as x counts its categories.

Against the rest

A histogram with facet="exclude" counts the other panels' rows, in grey behind each panel:

plot = (
    Trellis(penguins, wrap="species", cols=3, panel_height=170, title="Flipper length")
    .hist(x="flipper_length_mm", binwidth=2, facet="exclude", name="others")
    .hist(x="flipper_length_mm", binwidth=2, color="species")
)
plot

Box plots

A box goes from the first to the third quartile, with a line at the median, whiskers to the furthest values within 1.5 box heights (whis=), and the values beyond as points. With a category color=, the boxes go side by side. When y is the category column, the boxes lie sideways:

import polars as pl

cars = load("cars").with_columns(cyl=pl.col("cylinders").cast(pl.String))
plot = Trellis(cars, wrap="origin", cols=3, panel_height=150, title="Fuel use")
plot.box(x="mpg", y="cyl", tooltip=["name"])
plot

Hover a box for its quartiles, its count and its whiskers' reach; hover an outlier for its row (and its tooltip= columns). outliers=False leaves the points out.

The values themselves

A box hides how many values it summarises and how they lie. Points over it show them; jitter= spreads them across their category's band (a fraction of its width) so equal values don't hide each other. Each point keeps its place from draw to draw:

plot = Trellis(cars, wrap="origin", cols=3, panel_height=150, title="Fuel use")
plot.box(x="cyl", y="mpg", outliers=False)
plot.points(x="cyl", y="mpg", jitter=0.4, size=4, opacity=0.6, tooltip=["name"])
plot

Violins

A violin is a box plot with the shape of the values: each side is the values' density, with the median and the quartiles as lines across it. Like boxes, violins go side by side with a category color= (other than x), and lie sideways when y is the category column:

known = penguins.drop_nulls("sex")
plot = Trellis(known, wrap="species", cols=3, panel_height=170)
plot.violin(x="sex", y="flipper_length_mm", color="sex")
plot
Argument Sets
scale="area" every violin the same area; "count", areas as the rows' counts; "width", every violin as wide
inner="quartiles" the median and the quartiles inside; "points", each value; None, nothing
width=0.8 the widest violin, as a share of the step between positions
bw_adjust=1, cut=2 the bandwidth and how far past the values the shape goes, as for densities (below)
gridsize=100 the number of samples along each violin

Hover a violin for its count, median and quartiles. With inner="points", the values are points, and hovering one shows its row and its tooltip= columns.

Densities

A density is a smooth histogram: a Gaussian kernel density estimate, each curve covering an area of 1.

plot = Trellis(cars, wrap="origin", cols=3, panel_height=150)
plot.density(x="mpg", color="cyl", fill=True)
plot

bw_adjust= scales the bandwidth (as in seaborn: 2 is smoother, 0.5 more detailed), and cut= sets how far past the data each curve goes, in bandwidths.

Error bars

errorbar() draws each group's mean as a point, with a bar for its 95% confidence interval: how sure the mean is, not how spread the values are.

plot = Trellis(known, wrap="species", cols=3, panel_height=170)
plot.errorbar(x="sex", y="body_mass_g", color="sex")
plot
Argument Sets
extent="ci" the confidence interval for the mean; "se", the mean ± its standard error; "sd", ± the standard deviation; "range", the lowest to the highest value
level=0.95 the confidence interval's level
cap=0.25 the caps' width, as a share of the step between positions (0: no caps)
points=False leaves the means' points out

Hover a bar for its count, its mean and its ends.

Ends you computed

To draw intervals you already have (a model's predictions, quantiles), give the ends as columns: ymin= and ymax= with x as the positions, or xmin= and xmax= with y as the positions for sideways bars. The centre (y= or x=) is optional; without it, there are no points.

by_year = cars.group_by("year", "origin").agg(
    mpg=pl.col("mpg").median(),
    low=pl.col("mpg").quantile(0.25),
    high=pl.col("mpg").quantile(0.75),
)
plot = Trellis(by_year, wrap="origin", cols=3, panel_height=150, title="Middle half of mpg")
plot.errorbar(x="year", y="mpg", ymin="low", ymax="high", cap=0)
plot

Each row is one bar, and brushing it selects that row.

Which one?

You want to see Use
How many rows, and where hist()
Medians and spread, many groups side by side box()
The shape of each group, side by side violin()
The shape of a few groups, overlaid density()
Means and how sure they are errorbar()