Skip to content

Choose a facet layout

A trellis has two layouts: a wrap of one column's levels, filled row by row, or a grid that crosses two columns. Pick a wrap when the panels are a list (countries, stations, years); pick a grid when they are a table of two things (sex by species).

A wrap: wrap= and cols=

from anytrellis import Trellis
from anytrellis.datasets import load

penguins = load("penguins")
plot = Trellis(penguins, wrap="island", cols=3, panel_height=180)
plot.points(x="flipper_length_mm", y="body_mass_g", color="species")
plot

cols= sets how many panels go in a row; without it, a wrap has about the square root of the number of panels. When the last row is not full, the legend goes in its empty cells if it fits there.

A wrap of more than 100 panels shows them a page at a time; rows= sets a page's rows (see Page through many panels).

A grid: row= and col=

known = penguins.drop_nulls("sex")
plot = Trellis(known, row="sex", col="species", panel_height=150)
plot.points(x="bill_length_mm", y="bill_depth_mm", color="island")
plot

A grid keeps every combination, also those without rows, so its rows and columns stay aligned. row= alone makes a column of panels, and col= alone a row of them.

Several columns as one facet

Each of wrap=, row= and col= takes a list of columns too: a panel per combination of their levels.

plot = Trellis(penguins, wrap=["species", "island"], cols=3, panel_height=150)
plot.points(x="flipper_length_mm", y="body_mass_g", color="sex")
plot

Each column gets a strip, the first on the outside. A strip spans the panels next to each other that share its level, as ggh4x's nested strips do in R: here one Adelie strip over its three islands. A grid nests its strips the same way, the column strips stacked on top and the row strips side by side on the right, the first column's outermost.

strips="joined" shows one strip per panel instead, with the levels joined by ·:

Trellis(penguins, wrap=["species", "island"], strips="joined")

Either way, a panel's name in panels() and open() is its levels joined by · ("Adelie · Biscoe").

A grid with cells that can't have data

A grid has a cell for every combination of its rows and columns. Some combinations can't happen: a species that doesn't live on an island, a step that comes before the step it starts from. Those cells stay empty, and with many of them the grid is mostly empty frames. empty="blank" leaves them out. The other panels keep their rows and columns, and the axes are drawn into the blank cells next to them:

import polars as pl

counted = penguins.with_columns(
    title=pl.format("{} on {}: {} birds", "species", "island", pl.len().over("species", "island"))
)
plot = Trellis(counted, row="species", col="island", empty="blank", strip_label="title",
               panel_height=140)
plot.points(x="flipper_length_mm", y="body_mass_g", color="sex")
plot

Keep the default, empty="draw", when an empty cell is news: data that should be there and isn't. With page=, a cell is left out when it has no data on any page, so every page has the same cells and turning the pages moves nothing. A cell with data on some pages only is drawn, empty, on the others: there, its emptiness is news.

strip_label="title" names each panel with the value of a column, in a strip over the panel. The column must have one value per panel; make it with the data, as above, or in the database's query. A panel without one is named by its levels. The rows' and columns' strips go, since each panel names itself. The panel's name in panels() and open() stays its levels ("Adelie · Biscoe").

Margins: the rows and columns together

margins=True adds an "(all)" row under a grid's rows and an "(all)" column right of its columns, as ggplot2's facet_grid(margins = TRUE) does. Each panel of the (all) column has every row of its row, each panel of the (all) row every row of its column, and the corner has them all. Every layer draws them, and summaries (a smooth, a histogram, a box) are computed from their rows, so each margin shows what its row or column has in common:

cars = load("cars").filter(pl.col("cylinders").is_in([4, 6, 8]))
plot = Trellis(cars, row="origin", col="cylinders", margins=True, panel_height=110)
plot.points(x="horsepower", y="mpg", size=4).smooth(x="horsepower", y="mpg")
plot

margins="row" adds the (all) row alone, margins="col" the (all) column. A row selected in a margin is selected in its own panel too, and selected() has it once. Margins work with empty="blank" (a margin is drawn when its row or column has data) and with page= (each page's grid has its own), but not with load="pages", where the database summarises each panel's rows on its own.

Size

Argument Sets
panel_height=160 Each panel's height in pixels
height=600 The whole plot's height; the panels share it
aspect=1 Each panel's height as a multiple of its width: 1 is square
aspect="bank" The shape that shows the lines' median slope at 45 degrees
none of them Each panel is about 0.6 times as high as it is wide, from 90 to 300 pixels

The width is the notebook's or the page's. A plot keeps the width it is given and fits its panels in it.

Full screen and an opened panel take the room the screen gives. Panels with an aspect, banked or a number, keep their shape there: as large as fits, and narrower and centred when the screen is too low for the whole width. An image of a given height (save_png(height=...)) keeps it in the same way. Without an aspect, the panels stretch to the screen's height.

Banking to 45 degrees

How steep a line looks depends on the panel's shape, and changes are easiest to compare when the line's segments slope at about 45 degrees (Cleveland, Visualizing Data, 1993). aspect="bank" picks the shape that shows the median slope of every line's segments at 45 degrees, each measured in its own panel's ranges:

weather = load("seattle_weather").with_columns(
    year=pl.col("date").dt.year().cast(pl.String),
    day=pl.col("date").dt.ordinal_day().cast(pl.Float64),
)
plot = Trellis(weather, wrap="year", cols=1, aspect="bank")
plot.smooth(x="day", y="temp_max", span=0.3, se=False)
plot

It banks the smooth() fits, or without them the line() layers. Day-to-day noise has steep segments, so a noisy line alone banks to a flat, wide panel: add a smooth to bank the trend instead, with the line still drawn around it. Segments that neither rise nor fall don't count, and the shape stays between 0.02 and 5 times as high as wide. panel_height= and height= take precedence. With load="pages", the shape comes from the panels read first and stays as the pages turn.

Titles, a subtitle and a caption

plot = Trellis(
    cars, wrap="origin",
    title="Fuel use falls with weight in every region",
    subtitle="Miles per gallon by weight, 1970 to 1982 models",
    caption="Source: UCI Machine Learning Repository",
    labels={"mpg": "Fuel use (mpg)", "weight": "Weight (lb)", "cylinders": "Cylinders"},
)
plot.points(x="weight", y="mpg", color="cylinders")

A title can say what the plot shows; the subtitle under it, what is plotted, in what units, over what period; the caption under the plot, where the data come from. Readers remember annotated charts better, and the text is part of every image you export, from the page or with save_svg / save_png. A long subtitle or caption wraps.

labels= names columns for readers, once for the plot: the axis titles, the legend's title, the tooltips, a page column's title and the sort and filter menus show the label in place of the name. Code goes on naming columns as they are: select(color="Europe"), sort_panels("mean mpg"). A pairs plot shows the labels on its strips too.

x_title= and y_title= set an axis title outright, over its label:

Trellis(cars, wrap="origin", x_title="weight (lb)", y_title="miles per gallon")

A time axis has no title (dates say what they are) unless you give one; x_title="" hides any. The y title sits level over the plot's top left, ↑ miles per gallon, where it reads without tilting your head.

The look

Three themes come with anytrellis:

theme= What it draws
"minimal" (the default) Nothing behind the data but a faint grid (across y, and across x for points); strips as semibold titles at each panel's left; the y title level over the plot; Petroff's colour-vision-tested palette
"framed" After Observable Plot: a thin frame around each panel and more room between them, so each facet reads as one; strips centred over the panels; the x title at the end of its axis (weight →); d3's observable10 palette
"classic" anytrellis before 0.6: grey panels and strips, a full grid, titles on their side, tab10
Trellis(cars, row="origin", col="cylinders", theme="framed")

Change the look

A theme is a dozen settings, and anytrellis.Theme starts from a named one and changes any of them:

import anytrellis as at

roomy = at.Theme("minimal", frame=True, panel_gap=14, strip_align="center")
Trellis(cars, wrap="origin", theme=roomy)
Setting Values
panel_fill True: each panel filled light grey
frame True: a thin line around each panel
grid "auto" (across y, and across x for points), "x", "y", "both", "none"
grid_opacity the grid's opacity, 0 to 1 (it is the text colour, so it suits light and dark)
axis_lines which axes draw a line along the panels' edge: "x", "y", "both", "none"
strip_fill True: strips filled grey; False: the label alone, as a title
strip_align "left" or "center"
strip_bold semibold strip labels
y_title "top": level over the plot (↑ mpg); "side": on its side at the left
x_title "center" under the plot, or "end" of the axis (weight →)
row_labels a grid's row labels "level" at the right, or on their "side"
panel_gap pixels between panels
palette category colours: a name ("petroff10", "observable10", "tab10", ...) or a list

set_theme makes a theme the default of every plot made after it in the session, so a notebook sets it once at the top:

at.set_theme("framed", palette="tab10")
at.set_theme()                            # back to minimal

A plot's theme= and palette= still win over the session's. The theme is drawn the same in the notebook, in a saved page and in save_svg / save_png.

The legend's place

plot.legend("right", title="Cylinders")

"auto" (the default) puts it in a wrap's empty cells when it fits, and under the plot otherwise; "bottom" always puts it under the plot; "right" in a column right of the plot, the panels narrowed to make room (under the plot when it is too tall for that); "none" leaves it out. Trellis(legend=...) takes the same. title= names it, by default the colour column's label; with several colour columns, give a dict by column.

One panel at a time

Double-click a panel to see it alone (or press Enter over it); Page Up and Page Down step through the others at the same zoom, and Backspace goes back. From Python:

plot = Trellis(penguins, wrap="island").points(x="flipper_length_mm", y="body_mass_g")
print(plot.panels())
['Biscoe', 'Dream', 'Torgersen']
plot.open("Biscoe")   # a grid's panel: plot.open("female", "Gentoo")
plot.focused          # "Biscoe", also when opened in the browser
plot.close()