Trellis¶
Trellis
¶
Trellis(
data: Any = None,
*,
row: str | Sequence[str] | None = None,
col: str | Sequence[str] | None = None,
wrap: str | Sequence[str] | None = None,
cols: int | None = None,
rows: int | str | None = None,
page: str | Sequence[str] | None = None,
share_x: bool | str = True,
share_y: bool | str = True,
x_scale: str = "linear",
y_scale: str = "linear",
height: int | None = None,
panel_height: int | None = None,
aspect: float | str | None = None,
title: str = "",
subtitle: str = "",
caption: str = "",
labels: Mapping[str, str] | None = None,
x_title: str | None = None,
y_title: str | None = None,
palette: str
| Sequence[str]
| Mapping[str, str]
| None = None,
legend: str = "auto",
strips: str = "nested",
strip_label: str | None = None,
empty: str = "draw",
margins: bool | str = False,
fit_y: bool = False,
link: str | Sequence[str] | None = None,
load: str = "all",
theme: str | Theme | None = None,
renderer: str = "auto",
)
A trellis of panels: one per level of the facet columns, each drawn with the same layers, on shared scales unless told otherwise.
from anytrellis import Trellis
t = Trellis(df, wrap="station") # or row="site", col="year"
t.line(x="time", y="temp", color="sensor")
t # scroll to zoom: shared axes zoom together
Parameters:
-
data(Any, default:None) –The table the layers draw (Polars, PyArrow, pandas, DuckDB, Ibis, or a dict of arrays). A layer may bring its own; a layer whose data lacks the facet columns is drawn in every panel. A lazy table (a Polars
LazyFrame, a DuckDB relation, an Ibis table) is read in one query, with only the columns the plot uses, and computes the panels' summaries itself. -
row(str | Sequence[str] | None, default:None) –Facet column(s) whose levels are the grid's rows.
-
col(str | Sequence[str] | None, default:None) –Facet column(s) whose levels are the grid's columns.
-
wrap(str | Sequence[str] | None, default:None) –Facet column(s) whose levels are panels wrapped into
colscolumns (not withroworcol). -
cols(int | None, default:None) –Columns of a wrap (default: about the square root of the panels; 6 a page).
-
rows(int | str | None, default:None) –Rows of panels a page of a wrap shows: a wrap of more than 100 panels shows 4 at a time, and the reader turns the pages, sorts and filters the panels (by their statistics: see
panel_stats).rows=3pages any wrap;"all"never pages. Withpage: a page level with more panels than fit goes on several pages. -
page(str | Sequence[str] | None, default:None) –Column(s) whose levels are pages: each page shows one level's grid (
row,col: the same rows and columns on every page) or wrap (its panels, sorted and filtered as any paged wrap's). The reader picks the page by its level. -
share_x(bool | str, default:True) –Share the x scale:
True(all panels),"row","col","page"(the panels of a page ofpage),False(each panel its own) or"sliced"(each panel its own range, all as wide as the widest, so a change of 5 looks the same size in every panel; zooming one zooms all to its width). -
share_y(bool | str, default:True) –The same for y.
-
x_scale(str, default:'linear') –"linear"or"log"(log10: values of 0 or less are left out; a histogram's bins and a density are computed on the log scale). -
y_scale(str, default:'linear') –The same for y (not with marks drawn from zero: bars, areas, histograms, densities).
-
height(int | None, default:None) –The plot's height in CSS pixels (default: from
panel_height). -
panel_height(int | None, default:None) –Each panel's height in CSS pixels (default: from its width).
-
aspect(float | str | None, default:None) –Each panel's height as a multiple of its width (
1: square), or"bank": the one showing the lines' median slope at 45 degrees, where changes are easiest to compare (Cleveland's banking; thesmooth()fits', or without them theline()layers'), unlessheightorpanel_heightis given (default: about 0.62, between 90 and 300 px). -
title(str, default:'') –A title over the plot: what it shows, or better what it says.
-
subtitle(str, default:'') –A line or two under the title (what is plotted, the units, the period).
-
caption(str, default:'') –A note under the plot (the source, a footnote). Like the title and subtitle it is part of exported images.
-
labels(Mapping[str, str] | None, default:None) –Names to show for columns,
{"mpg": "Fuel use (mpg)"}: in the axis and legend titles, the tooltips, a page's title and the sort and filter menus (code still names columns as they are:pages(sort="mean mpg")). -
x_title(str | None, default:None) –The x axis title (default: the x column's label or name).
-
y_title(str | None, default:None) –The y axis title (default: the y column's label or name).
-
palette(str | Sequence[str] | Mapping[str, str] | None, default:None) –Colours for category colour columns: a list of colours, a name (
"petroff10","okabe-ito","observable10","tab10", ...; default: the theme's), or a dict giving categories their colours,{"Europe": "#1f77b4"}, so they keep them across plots (the others: the theme's colours that are left, in order). Number colour columns:colormap(). -
legend(str, default:'auto') –"auto": in a wrap's empty cells after its last panel when it fits there, under the plot otherwise;"bottom": always under the plot;"right": in a column right of the plot (under it when too tall);"none": no legend. Alsolegend(). -
strips(str, default:'nested') –With several facet columns,
"nested": a strip per column, each spanning the panels of its level (the first column's outermost);"joined": one strip per panel, row or column naming its levels together ("north · A"). -
strip_label(str | None, default:None) –A column whose value names each panel: every panel gets a strip of its own with it (a grid too), in place of the strips above. It must have one value per panel; a panel without one is named by its levels. Panel names in
panels()andopen()stay their levels. -
empty(str, default:'draw') –A grid's cells without data:
"draw"(empty panels, so a missing combination shows) or"blank"(left out, the others in their rows and columns: a triangle stays a triangle). Withpage=: the cells without data on every page, so each page has the same cells. -
margins(bool | str, default:False) –A grid's "(all)" panels, each of the rows of several panels (as ggplot2's
facet_grid(margins=TRUE)):"row", an (all) row under the rows, each panel the rows of its column;"col", an (all) column right of the columns, each panel the rows of its row;True, both and a corner of every row. Every layer draws them, summaries (hist, box, smooth, ...) computed of their rows. -
fit_y(bool, default:False) –Start with y fitted to the data in view: zooming or panning x refits each y scale (shared ones to all their panels), until y is zoomed by hand. The
ykey and the toolbar switch it on and off. -
link(str | Sequence[str] | None, default:None) –Column(s) that identify a thing across panels (a country, a station): a selection grows to every row sharing them, in all panels and layers that have the columns. Select a few countries in 1955 and see them in every year. (Separate plots sharing a selection:
anytrellis.link.) -
load(str, default:'all') –How a lazy table's rows are read:
"all"(every row, once) or"pages"(a paged wrap: only the rows of the panels of the page shown and the pages either side of it, read again as the reader turns the pages; the panels' statistics, the axes' ranges and the colours' levels come from the database). For a table in a database: lines, points and text drawn from the plot's data (other layers bring their own); not withlink.save_htmlstill reads every row. -
theme(str | Theme | None, default:None) –How the plot looks:
"minimal","framed","classic", or ananytrellis.Themechanging any of their settings (default:"minimal", or whatanytrellis.set_themeset). minimal: nothing behind the data but a faint grid (across y, and x for points), strips as titles at the left, the y title level over the plot ("↑ temp"), Petroff's colour-vision-tested palette. framed (after Observable Plot): a thin frame around each panel and more room between them, strips centred, the x title at its axis' end, d3's observable10. classic (the look before 0.6): grey panels and strips, a full grid, titles on their side, tab10. Every theme but classic leaves a time axis untitled unlessx_titleis given. -
renderer(str, default:'auto') –"auto"(WebGPU, then WebGL2, then Canvas 2D), or one of them.
focused
property
¶
focused: str | None
The opened panel's name (opened here or in the browser), or None.
pages
property
¶
pages: int
The number of pages, with the panels the filters keep (1 when it does not page).
page_names
property
¶
page_names: list[str]
Each page's name: its level of the page columns (page=), with "(2 of 3)"
after it when the level has more pages; without page columns, "".
selection
property
¶
selection: dict[str, Any] | None
The selection (made here or in the browser): {"x": ..., "y": ..., "color": ...,
"panel": ...}, each axis a (low, high) range (times as datetime64; a
category axis: the categories in it) or None for any, the colours chosen in the
legend (a list of categories) or None for any, and the panel it was drawn in (a
linked plot) or None for all; None when nothing is selected.
widget
property
¶
widget: TrellisWidget
The widget that shows the plot: made the first time the plot is shown or this is read, then the same one.
line
¶
line(
data: Any = None,
*,
x: str,
y: str,
color: str | None = None,
group: str | Sequence[str] | None = None,
step: str | None = None,
width: float = 1.5,
opacity: float = 1.0,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
Lines through the points of each series, sorted by x; or steps between them.
t = Trellis(gapminder, wrap="region")
t.line(x="year", y="life_expect", group="country", width=1)
t.line(x="time", y="state", step="post") # each value holds until the next
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column.
-
y(str) –The y column.
-
color(str | None, default:None) –A colour column (one line per category; numbers along a colormap) or one colour.
-
group(str | Sequence[str] | None, default:None) –Column(s) whose combinations are separate lines (besides
color). -
step(str | None, default:None) –Steps instead of slopes:
"post"(each value holds until the next point: a level that changes at the points, as a counter or a state),"pre"(each value holds back to the point before) or"mid"(each holds to halfway between the points). -
width(float, default:1.5) –Line width in CSS pixels.
-
opacity(float, default:1.0) –0 to 1.
-
facet(FacetMode, default:'auto') –"auto"(each row in its panel; every panel when the data has no facet columns),"include","all"(every row in every panel) or"exclude"(each panel shows the other panels' rows: grey context). -
tooltip(Sequence[str], default:()) –Columns shown on hover, besides x and y.
-
name(str | None, default:None) –The layer's name.
points
¶
points(
data: Any = None,
*,
x: str,
y: str,
color: str | None = None,
size: float = 5.0,
opacity: float = 0.85,
jitter: float = 0.0,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
A point per row.
t = Trellis(penguins, wrap="species")
t.points(x="flipper_length_mm", y="body_mass_g", color="sex")
t.box(x="species", y="body_mass_g").points(x="species", y="body_mass_g", jitter=0.4)
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column.
-
y(str) –The y column.
-
color(str | None, default:None) –A colour column or one colour.
-
size(float, default:5.0) –Diameter in CSS pixels.
-
opacity(float, default:0.85) –0 to 1.
-
jitter(float, default:0.0) –Spread the points of a category axis across their band, up to this fraction of its width (0 to 1; 0.4 is a strip plot's), so points with the same value don't hide each other. Each row keeps its place from draw to draw.
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown on hover, besides x and y.
-
name(str | None, default:None) –The layer's name.
bars
¶
bars(
data: Any = None,
*,
x: str,
y: str,
color: str | None = None,
position: Position = "stack",
width: float = 0.8,
opacity: float = 1.0,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
Bars from 0 to y at each x (categories, numbers or times); with a category y and x not, horizontal bars from 0 to x at each y.
Trellis(barley, wrap="site").bars(x="variety", y="yield", color="year", position="dodge")
Trellis(barley, wrap="site").bars(x="yield", y="variety", color="year") # horizontal
Trellis(barley, wrap="site").bars(x="variety", y="yield", color="year", position="fill")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column (horizontal bars: their lengths).
-
y(str) –The bar heights (horizontal bars: a category column, their positions).
-
color(str | None, default:None) –A colour column or one colour.
-
position(Position, default:'stack') –With a category colour:
"stack"(default),"fill"(stacked as shares of each stack, every stack as tall as 1: the composition, whatever the totals),"dodge"(side by side) or"identity"(overlapping). -
width(float, default:0.8) –Bar width as a fraction of the step between positions.
-
opacity(float, default:1.0) –0 to 1.
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown on hover, besides x and y.
-
name(str | None, default:None) –The layer's name.
area
¶
area(
data: Any = None,
*,
x: str,
y: str,
color: str | None = None,
group: str | Sequence[str] | None = None,
position: Position = "stack",
opacity: float = 0.8,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
Filled areas under the line of each series, down to 0.
Trellis(by_region).area(x="year", y="pop", color="region")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column.
-
y(str) –The y column.
-
color(str | None, default:None) –A colour column (one area per category) or one colour.
-
group(str | Sequence[str] | None, default:None) –Column(s) whose combinations are separate areas (besides
color). -
position(Position, default:'stack') –"stack"(default: each series on the ones before it, at equal x),"fill"(stacked as shares of the total at each x, up to 1) or"identity"(each from 0, overlapping). -
opacity(float, default:0.8) –0 to 1.
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown on hover, besides x and y.
-
name(str | None, default:None) –The layer's name.
band
¶
band(
data: Any = None,
*,
x: str,
ymin: str,
ymax: str,
color: str | None = None,
group: str | Sequence[str] | None = None,
opacity: float = 0.3,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
A band between two lines: from ymin to ymax along x (a range, an
interval, an envelope), one per group (and colour).
Trellis(weather, wrap="year").band(x="date", ymin="temp_min", ymax="temp_max")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column.
-
ymin(str) –The lower line's column.
-
ymax(str) –The upper line's column.
-
color(str | None, default:None) –A colour column or one colour.
-
group(str | Sequence[str] | None, default:None) –Column(s) splitting the rows into separate bands.
-
opacity(float, default:0.3) –0 to 1.
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown on hover, besides x, ymin and ymax.
-
name(str | None, default:None) –The layer's name.
smooth
¶
smooth(
data: Any = None,
*,
x: str,
y: str,
color: str | None = None,
method: str = "loess",
se: bool = True,
level: float = 0.95,
span: float = 0.75,
n: int = 80,
fullrange: bool = False,
width: float = 1.5,
opacity: float = 1.0,
facet: FacetMode = "auto",
name: str | None = None,
) -> Self
A smooth line through each panel's points (and each colour's), with a confidence band for its mean.
t = Trellis(cars, wrap="origin")
t.points(x="horsepower", y="mpg").smooth(x="horsepower", y="mpg")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column (numbers or times).
-
y(str) –The y column.
-
color(str | None, default:None) –A category column (a fit per category) or one colour.
-
method(str, default:'loess') –"loess"(local linear regression, tricube weights) or"linear"(least squares). -
se(bool, default:True) –Draw the confidence band.
-
level(float, default:0.95) –The band's confidence level.
-
span(float, default:0.75) –Loess: the share of the points each local fit uses.
-
n(int, default:80) –Points along each line.
-
fullrange(bool, default:False) –Draw each line over every panel's x range, not its own data's.
-
width(float, default:1.5) –Line width in CSS pixels.
-
opacity(float, default:1.0) –0 to 1 (the band is lighter).
-
facet(FacetMode, default:'auto') –As for
line. -
name(str | None, default:None) –The layer's name.
rect
¶
rect(
data: Any = None,
*,
x: str,
y: str,
x2: str | None = None,
y2: str | None = None,
color: str | None = None,
width: float = 1.0,
height: float = 1.0,
opacity: float = 1.0,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
Rectangles: tiles centred on (x, y), one step of the data wide and high (a heatmap, with a number colour), or from (x, y) to (x2, y2).
Trellis(daily, wrap="year").rect(x="day", y="month", color="temp_max")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column (the tiles' centres, or their left with
x2). -
y(str) –The y column (centres, or bottoms with
y2). -
x2(str | None, default:None) –The tiles' right edges.
-
y2(str | None, default:None) –The tiles' tops.
-
color(str | None, default:None) –A colour column or one colour (numbers: a colormap, as a heatmap).
-
width(float, default:1.0) –A tile's width as a fraction of the step between x values.
-
height(float, default:1.0) –A tile's height as a fraction of the step between y values.
-
opacity(float, default:1.0) –0 to 1.
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown on hover, besides x and y (a number colour: shown).
-
name(str | None, default:None) –The layer's name.
text
¶
text(
data: Any = None,
*,
x: str,
y: str,
text: str,
color: str | None = None,
size: float = 11.0,
align: str = "center",
dx: float = 0.0,
dy: float = 0.0,
opacity: float = 1.0,
facet: FacetMode = "auto",
name: str | None = None,
) -> Self
A label per row: the text column's value at (x, y).
t.text(x="fertility", y="life_expect", text="country", align="left", dx=6)
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The x column.
-
y(str) –The y column.
-
text(str) –The column of labels.
-
color(str | None, default:None) –A colour column or one colour (default: the theme's text colour).
-
size(float, default:11.0) –Font size in CSS pixels.
-
align(str, default:'center') –"left","center"or"right"of the point. -
dx(float, default:0.0) –Offset to the right, in CSS pixels.
-
dy(float, default:0.0) –Offset down, in CSS pixels.
-
opacity(float, default:1.0) –0 to 1.
-
facet(FacetMode, default:'auto') –As for
line. -
name(str | None, default:None) –The layer's name.
hist
¶
hist(
data: Any = None,
*,
x: str,
color: str | None = None,
bins: int | Sequence[Any] = 30,
binwidth: Any = None,
stat: str = "count",
position: Position = "stack",
width: float | None = None,
opacity: float = 1.0,
facet: FacetMode = "auto",
name: str | None = None,
) -> Self
A histogram in each panel: the rows counted in bins that every panel shares.
Trellis(penguins, wrap="species").hist(x="flipper_length_mm", binwidth=2, color="sex")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The column binned (numbers or times); a category column: its categories counted.
-
color(str | None, default:None) –A category column (its counts stacked or overlapping) or one colour.
-
bins(int | Sequence[Any], default:30) –The number of bins over the values' range, or the edges.
-
binwidth(Any, default:None) –A bin width instead (a time axis: a timedelta, or
"7D","6h"), the edges at its multiples. -
stat(str, default:'count') –"count","percent"(of each panel's rows) or"density"(each panel's bars cover an area of 1). -
position(Position, default:'stack') –With a colour:
"stack"(default),"fill"(each bin's colours as shares of it, up to 1) or"identity"(overlapping). -
width(float | None, default:None) –Bar width as a fraction of the bin (default 1; categories 0.8).
-
opacity(float, default:1.0) –0 to 1.
-
facet(FacetMode, default:'auto') –As for
line;"exclude": the other panels' histogram, in grey. -
name(str | None, default:None) –The layer's name.
box
¶
box(
data: Any = None,
*,
x: str,
y: str,
color: str | None = None,
position: Position = "dodge",
width: float = 0.8,
whis: float = 1.5,
outliers: bool = True,
linewidth: float = 1.5,
size: float = 4.0,
opacity: float = 1.0,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
Box plots: a box per position (and colour) in each panel, from the first to the
third quartile with a line at the median, whiskers to the furthest values within
whis times the box's height of it, and the values beyond as points.
Trellis(penguins, wrap="island").box(x="body_mass_g", y="species")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The positions (categories, or numbers), or the values for horizontal boxes.
-
y(str) –The values, or (a category column) the positions of horizontal boxes.
-
color(str | None, default:None) –A category column (its boxes side by side) or one colour.
-
position(Position, default:'dodge') –With a colour:
"dodge"(default, side by side) or"identity". -
width(float, default:0.8) –Box width as a fraction of the step between positions.
-
whis(float, default:1.5) –Whisker reach, in interquartile ranges (Tukey: 1.5).
-
outliers(bool, default:True) –Draw the values beyond the whiskers.
-
linewidth(float, default:1.5) –The box's outline, median and whiskers, in CSS pixels.
-
size(float, default:4.0) –Outlier diameter in CSS pixels.
-
opacity(float, default:1.0) –0 to 1 (the box's fill is lighter).
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown when hovering an outlier.
-
name(str | None, default:None) –The layer's name.
density
¶
density(
data: Any = None,
*,
x: str,
color: str | None = None,
fill: bool = False,
bw_adjust: float = 1.0,
cut: float = 3.0,
gridsize: int = 200,
width: float = 1.5,
opacity: float = 1.0,
facet: FacetMode = "auto",
name: str | None = None,
) -> Self
A density curve in each panel (and for each colour): a Gaussian kernel density estimate, each curve covering an area of 1, on x values every panel shares.
Trellis(penguins, wrap="species").density(x="body_mass_g", color="sex", fill=True)
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The column (numbers or times).
-
color(str | None, default:None) –A category column (a curve per category) or one colour.
-
fill(bool, default:False) –Fill the area under each curve too.
-
bw_adjust(float, default:1.0) –The bandwidth, as a multiple of Scott's rule's.
-
cut(float, default:3.0) –How far past the data each curve goes, in bandwidths.
-
gridsize(int, default:200) –Points along the shared x grid.
-
width(float, default:1.5) –Line width in CSS pixels.
-
opacity(float, default:1.0) –0 to 1 (a fill is lighter).
-
facet(FacetMode, default:'auto') –As for
line. -
name(str | None, default:None) –The layer's name.
horizon
¶
horizon(
data: Any = None,
*,
x: str,
y: str,
bands: int = 3,
origin: float = 0.0,
step: float | None = None,
name: str | None = None,
) -> Self
A horizon chart in each panel: a series in a short panel, its distance from
origin cut into bands, each band laid over the one before in the panel's height
and darker, blues above the origin and reds below it (folded up). A hundred series
fit on a screen, and their highs and lows still show (Heer, Kong and Agrawala 2009).
Trellis(readings, wrap="station", cols=1, panel_height=24).horizon(
x="time", y="temp", origin=10)
The y axis shows the height within a band; the legend names each band's range.
Each panel draws one series: give each x one y. Margins (margins=) are left
empty, since each has several panels' series.
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The column along the panel (numbers or times).
-
y(str) –The values (numbers).
-
bands(int, default:3) –Bands on each side of the origin.
-
origin(float, default:0.0) –The value the bands start from.
-
step(float | None, default:None) –Each band's height in y's units (default: a round number, so the bands reach the farthest value from the origin in any panel; values past the last band fill it).
-
name(str | None, default:None) –The layer's name.
violin
¶
violin(
data: Any = None,
*,
x: str,
y: str,
color: str | None = None,
position: Position = "dodge",
width: float = 0.8,
scale: str = "area",
inner: str | None = "quartiles",
bw_adjust: float = 1.0,
cut: float = 2.0,
gridsize: int = 100,
linewidth: float = 1.0,
size: float = 3.0,
opacity: float = 1.0,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
Violins: the values' distribution at each position (and colour) in each panel, as their density mirrored around the position, with the median and quartiles inside. Where a box plot shows five numbers, a violin shows the shape: two peaks, a long tail.
Trellis(penguins, wrap="island").violin(x="species", y="body_mass_g")
Trellis(penguins).violin(x="body_mass_g", y="species", color="sex") # horizontal
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str) –The positions (categories, or numbers), or the values for horizontal violins.
-
y(str) –The values, or (a category column) the positions of horizontal violins.
-
color(str | None, default:None) –A category column (its violins side by side) or one colour.
-
position(Position, default:'dodge') –With a colour:
"dodge"(default, side by side) or"identity". -
width(float, default:0.8) –The widest violin's width, as a fraction of the step between positions.
-
scale(str, default:'area') –"area"(every violin the same area),"count"(areas as the number of values) or"width"(every violin as wide). -
inner(str | None, default:'quartiles') –"quartiles"(the median across it, the quartiles half way),"points"(the values, along its middle) or None. -
bw_adjust(float, default:1.0) –The bandwidth, as a multiple of Scott's rule's.
-
cut(float, default:2.0) –How far past the values each violin goes, in bandwidths.
-
gridsize(int, default:100) –Points along each violin.
-
linewidth(float, default:1.0) –The outline's (and the quartiles') width in CSS pixels.
-
size(float, default:3.0) –The values' diameter in CSS pixels (
inner="points"). -
opacity(float, default:1.0) –0 to 1 (the fill is lighter).
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown when hovering a value (
inner="points"). -
name(str | None, default:None) –The layer's name.
errorbar
¶
errorbar(
data: Any = None,
*,
x: str | None = None,
y: str | None = None,
ymin: str | None = None,
ymax: str | None = None,
xmin: str | None = None,
xmax: str | None = None,
extent: str = "ci",
level: float = 0.95,
color: str | None = None,
position: Position = "dodge",
width: float = 0.8,
cap: float = 0.25,
points: bool = True,
linewidth: float = 1.5,
size: float = 6.0,
opacity: float = 1.0,
facet: FacetMode = "auto",
tooltip: Sequence[str] = (),
name: str | None = None,
) -> Self
Error bars: an interval at each position, with caps, and its centre as a point.
From the values: the mean of each position's (and colour's) values with an
interval around it (extent). Or as given: from ymin to ymax at each x
(xmin to xmax at each y: horizontal), centred on y (x) if given.
Trellis(penguins, wrap="island").errorbar(x="species", y="body_mass_g") # mean, 95% CI
Trellis(fits, wrap="site").errorbar(x="dose", y="effect", ymin="lo", ymax="hi")
Parameters:
-
data(Any, default:None) –The layer's table (default: the plot's).
-
x(str | None, default:None) –The positions; or the values (a category
y), or the centres (withxminandxmax). -
y(str | None, default:None) –The values (a category or number
x); or the centres (withyminandymax), or the positions (withxminandxmax). -
ymin(str | None, default:None) –Each vertical bar's low end (with
ymax). -
ymax(str | None, default:None) –Its high end.
-
xmin(str | None, default:None) –Each horizontal bar's low end (with
xmax). -
xmax(str | None, default:None) –Its high end.
-
extent(str, default:'ci') –From the values:
"ci"(the mean'slevelconfidence interval),"se"(the mean ± its standard error),"sd"(± one standard deviation) or"range"(the lowest value to the highest). On a log axis, of the logs (the centre is the geometric mean). -
level(float, default:0.95) –The confidence level of
extent="ci". -
color(str | None, default:None) –A category column (its bars side by side) or one colour.
-
position(Position, default:'dodge') –With a colour:
"dodge"(default, side by side) or"identity". -
width(float, default:0.8) –The room the bars of a position share (dodged), as a fraction of the step between positions.
-
cap(float, default:0.25) –The caps' width, as a fraction of each bar's room: the step between positions, or its share of it when dodged (0: no caps).
-
points(bool, default:True) –Draw the centre as a point.
-
linewidth(float, default:1.5) –In CSS pixels.
-
size(float, default:6.0) –The centre's diameter in CSS pixels.
-
opacity(float, default:1.0) –0 to 1.
-
facet(FacetMode, default:'auto') –As for
line. -
tooltip(Sequence[str], default:()) –Columns shown on hover (bars as given).
-
name(str | None, default:None) –The layer's name.
rule
¶
rule(
data: Any = None,
*,
x: Any = None,
y: Any = None,
color: str = "#6b7480",
width: float = 1.0,
dash: Sequence[float] = (),
name: str | None = None,
) -> Self
Reference lines: vertical at x, or horizontal at y. A value or a list of
values: across every panel. With a table, a column of it: a line per row, in the
panel of its facet columns' values (a table without them: in every panel), so each
panel can have its own target, mean or limit.
t.rule(y=0, color="#888888", dash=(4, 3))
targets = pl.DataFrame({"site": ["Crookston", "Morris"], "target": [40, 35]})
Trellis(barley, wrap="site").points(x="yield", y="variety").rule(targets, x="target")
Parameters:
-
data(Any, default:None) –A table of the lines' positions (and the facet columns), or None.
-
x(Any, default:None) –Position(s) of vertical lines; with
data, its column of them. -
y(Any, default:None) –Position(s) of horizontal lines; with
data, its column of them. -
color(str, default:'#6b7480') –Their colour.
-
width(float, default:1.0) –Line width in CSS pixels.
-
dash(Sequence[float], default:()) –A dash pattern in pixels, e.g.
(4, 3). -
name(str | None, default:None) –The layer's name.
share
¶
share(
x: bool | str | None = None, y: bool | str | None = None
) -> Self
Share scales across panels: True (all), "row", "col", "page",
False (each panel its own) or "sliced" (each its own range, all as wide as the
widest). Panels that share a scale also zoom together.
scale
¶
scale(x: str | None = None, y: str | None = None) -> Self
The axes' scales: "linear" or "log" (as Trellis(x_scale=...)).
limits
¶
limits(
x: tuple[Any, Any] | None = None,
y: tuple[Any, Any] | None = None,
) -> Self
The axes' ranges, (low, high), either end None for the data's own:
t.limits(y=(0, None)) starts y at 0. Times as dates or datetimes (("2026-03-01",
None)), a log axis's in its values. Zooming starts there and Reset comes back there.
(None, None): the data's range again.
format
¶
format(
x: str | None = None,
y: str | None = None,
*,
color: str | None = None,
) -> Self
How values are written on the axes, in tooltips and at a colour legend's ends:
d3-format strings for numbers (",.0f": 1,235; ".1%": 12.3%; ".2s": 1.2k;
"$,.2f"), strftime strings for times ("%b %Y": Mar 2026; "%-d %b": 2 Mar;
"%H:%M"), in UTC as the axis is. "": the automatic labels again.
t.format(x="%b %Y", y=".0%")
legend
¶
legend(
position: str | None = None,
*,
title: str | Mapping[str, str] | None = None,
) -> Self
Where the legend goes, and its title.
Parameters:
-
position(str | None, default:None) –"auto"(in a wrap's empty cells when it fits, else under the plot),"bottom","right"(a column right of the plot; under it when too tall) or"none". -
title(str | Mapping[str, str] | None, default:None) –The colour legend's title (default: the colour column's label or name); with several colour columns, a dict by column.
as_category
¶
as_category(*columns: str) -> Self
Read number columns as categories: their distinct values are the levels, in
order (-10, -2, 3), labelled as numbers (4, not 4.0), rows without a
value last. A colour then takes the palette's colours and a legend of the levels,
an axis a band each, group= a series each, as a text column would.
t.as_category("cylinders").points(x="weight", y="mpg", color="cylinders")
t.as_category("cylinders").order("cylinders", [8, 6, 4])
order
¶
order(
column: str,
levels: Sequence[Any] | None = None,
*,
by: Summary | None = None,
of: str | None = None,
descending: bool = False,
) -> Self
Order a category column's levels (a number column's too, read as categories:
as_category): as levels lists them (the rest after), or
by a summary of a column per level (Cleveland's ordering by the median, for one),
rather than alphabetically. This orders panels (facet columns), bands on an axis
and colours alike.
t.order("site", by="median", of="yield")
t.order("month", ["Jan", "Feb", "Mar"])
panels
¶
panels() -> list[str]
The panels' names, in order: each panel's level of every facet column, joined by
· ("north · s1" in a grid of region by sensor).
open
¶
open(*panel: Any) -> Self
Show one panel alone, on the whole plot (as a double-click on it does): by its
name (see panels()) or by its level of each facet column.
t.open("station 3") # wrap="station"
t.open("north", "s1") # row="region", col="sensor"
The zoom stays linked: back in the grid, the panels sharing its scales show what
the opened panel showed. close() (or Backspace, Esc, a double-click) goes back.
panel_stats
¶
panel_stats(data: Any) -> Self
Statistics of each panel, to sort and filter a paged wrap's panels by: a table
with the facet columns and one row per panel; each other column is a statistic
(numbers, or text). They join the ones the plot computes (rows, and the mean,
median, min, max, sd and trend of the values drawn).
info = df.group_by("station").agg(pl.col("temp").quantile(0.9).alias("p90 temp"),
pl.col("region").first())
t.panel_stats(info)
stats
¶
stats() -> dict[str, list[Any]]
The panels' statistics, to sort and filter by: {name: [a value per panel]},
in the order of panels() (empty when the plot does not page).
sort_panels
¶
sort_panels(
by: str | None = None, *, descending: bool = False
) -> Self
Sort a paged wrap's panels by a statistic (a name from stats()), as the
reader can in the browser; None: as given (order). Panels without a value
go last.
t.sort_panels("trend temp", descending=True) # the steepest rise first
filter_panels
¶
filter_panels(name: str = '', **where: Any) -> Self
Show only the panels whose name has every word of name, and whose
statistics are in the ranges given: (low, high) for numbers (None: open),
a piece of text for text. filter_panels() shows them all again. A statistic's
name with spaces goes in a dict: filter_panels(**{"mean temp": (20, None)}).
t.filter_panels("north")
t.filter_panels(rows=(100, None), region="Europe")
show_page
¶
show_page(page: int | str) -> Self
Turn to a page: by number (from 1), or by its name (see page_names: a level
of the page columns, the first of its pages).
t.show_page(3)
t.show_page("Amsterdam") # page="site"
shown_panels
¶
shown_panels() -> list[str]
The names of the panels on the page shown, in order (all panels when it does not page).
select
¶
select(
x: Any = None,
y: Any = None,
*,
color: Any = None,
panel: Any = None,
) -> Self
Select the marks in a range of x, of y or of both, as a brush drawn in the
browser does: in every panel, or in panel alone (a name from panels(), or a
tuple of its levels); with link, also every row sharing a key with them, in all
panels. color: only the marks of these colours, as clicking legend entries does.
select() clears the selection.
t.select(x=("2026-03-05", "2026-03-08")) # a time axis: dates, datetimes
t.select(x=(2, 4), y=(60, 80)) # numbers
t.select(x=["Europe", "Asia"]) # a category axis: its categories
t.select(x=(0, 3), panel="1955") # with link="country": follow them
t.select(color=["Asia", "Africa"]) # a colour column's categories
selected
¶
selected(layer: str | int | None = None) -> Any
The selected rows of a layer's data (default: the first layer), as the same kind
of table (Polars, pandas, PyArrow, ...); none selected: no rows. In a linked plot
(anytrellis.link) without a brush of its own: the rows another plot selects.
to_html
¶
to_html(*, title: str | None = None) -> str
The plot as a standalone HTML page: data and code inside, no kernel needed.
save_html
¶
save_html(
path: str | Path, *, title: str | None = None
) -> Path
Write to_html to a file; returns its path.
save_svg
¶
save_svg(
path: str | Path,
*,
width: float | None = None,
height: float | None = None,
theme: str = "light",
) -> Path
Write the plot as an SVG image, drawn in Python (no browser needed: a script, a CI job); returns its path. It is the plot as shown: the zoom it was last shown with, the selection and an opened panel, every mark, axis and label a vector element.
t.save_svg("temperatures.svg")
t.save_svg("slide.svg", width=1200, height=600, theme="dark")
Parameters:
-
path(str | Path) –The file to write.
-
width(float | None, default:None) –The image's width in CSS pixels (default: the width the plot was last shown at, else 800).
-
height(float | None, default:None) –The image's height in CSS pixels (default: as the plot lays out); panels with an
aspectkeep their shape within it. -
theme(str, default:'light') –"light"or"dark".
save_png
¶
save_png(
path: str | Path,
*,
width: float | None = None,
height: float | None = None,
theme: str = "light",
scale: float = 2.0,
) -> Path
Write the plot as a PNG image, drawn in Python as save_svg draws it, with
scale pixels per CSS pixel (2: sharp on slides and high-density screens);
returns its path. Needs resvg-py: pip install "anytrellis[png]".
t.save_png("temperatures.png")
t.save_png("thumbnail.png", width=400, scale=1)
colormap
¶
colormap(
colormap: str | Sequence[str] | None = None,
*,
scale: str | None = None,
midpoint: float | None = None,
bins: int | None = None,
) -> Self
How number colour columns take their colours.
t.colormap("cividis") # another colormap
t.colormap(scale="diverging", midpoint=0) # change from zero: RdBu, red high
t.colormap("Blues", scale="binned", bins=6) # about six steps of round width
t.colormap(scale="quantile", bins=4) # four steps, as many values each
Parameters:
-
colormap(str | Sequence[str] | None, default:None) –"viridis"(the default),"cividis","magma","Blues","RdBu","PuOr", each reversed with"_r", or a list of colours, low to high. -
scale(str | None, default:None) –"linear"(the default): lowest to highest along the colormap;"diverging": both sides ofmidpointequally deep, the colormap's middle at it (default colormap:"RdBu_r");"binned": steps of round width, a colour each, read back from the legend's ranges;"quantile": steps holding as many values each. -
midpoint(float | None, default:None) –The value a diverging scale centres on (default 0).
-
bins(int | None, default:None) –About how many steps a binned scale has, and how many a quantile one has (2 to 20, default 5).