Plot your own tables¶
Give Trellis any table: a Polars, pandas or PyArrow table, a Polars LazyFrame, a
DuckDB relation, an Ibis table, or a dict of columns (lists or NumPy arrays). Name its
columns in the facets and the layers.
import pandas as pd
from anytrellis import Trellis
df = pd.DataFrame({
"day": pd.date_range("2026-01-01", periods=90, freq="D").repeat(2),
"shop": ["north", "south"] * 90,
"visitors": [120 + (i % 7) * 15 + (i // 2) for i in range(180)],
})
plot = Trellis(df, wrap="shop", panel_height=160).line(x="day", y="visitors")
plot
selected() gives the selected rows back as the same kind of table: a pandas table here.
Columns and their axes¶
| Column | Axis | Notes |
|---|---|---|
| Numbers | A number axis | Integers and floats; NaN and nulls are left out of a layer |
| Dates and datetimes | A time axis | Ticks from years to fractions of a second, as you zoom |
| Text and categories | A category axis | A band per category, in alphabetical order unless ordered; nulls become a (missing) category |
A pandas Categorical and a Polars Enum keep their declared order. Booleans count as the
numbers 0 and 1: t.as_category("flag") reads them as categories, as it does numbers you
want as categories, such as years in a bar chart. A facet column can be any of these
kinds; its levels are the panels.
A dict of columns¶
For data that is not in a table library yet, a dict of equally long columns works:
import numpy as np
rng = np.random.default_rng(1)
columns = {
"group": np.repeat(["a", "b", "c"], 200),
"x": rng.normal(size=600),
"y": rng.normal(size=600),
}
plot = Trellis(columns, wrap="group", panel_height=150).points(x="x", y="y", size=4)
plot
The synthetic data in these guides are dicts like this.
A layer with its own table¶
Each layer can bring its own table as its first argument. A layer whose table has the facet columns is split into panels like the plot's; one whose table lacks them is drawn in every panel. Here, a table of targets drawn behind each shop's line:
targets = pd.DataFrame({
"day": pd.to_datetime(["2026-01-01", "2026-03-31"]),
"visitors": [150, 250],
})
plot = (
Trellis(df, wrap="shop", panel_height=160)
.line(targets, x="day", y="visitors", color="#999999", name="target")
.line(x="day", y="visitors", name="visitors")
)
plot
facet="all" draws every row of a layer in every panel even when it has the facet
columns, and facet="exclude" draws the other panels' rows: see
each group against the rest.
Lazy tables and databases¶
A Polars LazyFrame, a DuckDB relation or an Ibis table (on DuckDB, Postgres, Snowflake or
any other database Ibis queries) is read when the plot is first drawn: in one query, with
only the columns the plot uses. The summaries of each panel are computed by the database:
the statistics the pages sort and filter by, and those order() ranks levels
by. The medians of millions of rows come from it, not from Python.
import ibis
con = ibis.duckdb.connect("readings.duckdb")
readings = con.table("readings").filter(ibis._.year == 2025)
plot = Trellis(readings, wrap="station").line(x="time", y="temp")
Ten million readings of 1,000 stations, from an Ibis table on DuckDB, are drawn in 3.3 s rather than 5.3 s, and their unused columns are never read.
- The rows of the columns drawn are read into Python, as for any table, and the browser gets the panels of the pages around the one shown.
- A column needed later (a tooltip column of a layer added after the plot was drawn,
say) reads the table again, with it. The rows must come back in the same order each
time, as they do from Polars, DuckDB and Ibis on DuckDB. For a database that promises
no order, sort the table by a unique key first (
readings.order_by("id")). selected()gives every column of the selected rows, as the table the query collects to: a PyArrow table from DuckDB and Ibis, a PolarsDataFramefrom aLazyFrame.- A summary the database can't compute (the mean of times, on some backends) is computed from the rows instead.
Reading a page at a time¶
With load="pages", a paged wrap reads only the rows of the panels of the page shown and
the pages either side of it: Python never holds the whole table. Turning the page reads the
rows of the next panels (a query of the facet columns' values), and the browser draws them
as it draws any paged plot's.
import duckdb
con = duckdb.connect("readings.duckdb")
plot = Trellis(con.table("readings"), wrap="station", load="pages")
plot.line(x="time", y="temp", color="humidity")
What a page needs of the other rows comes from the database, so every page looks as it would with every row read: the panels (the facet columns' combinations), their statistics (and their trend, as a window query), each panel's range of x and y, the levels of the category columns and the range of the number colours.
Ten million readings of 1,000 stations, from DuckDB, are drawn in 1.0 s rather than 3.9 s,
from 480,000 rows read rather than all of them. Turning a page keeps the rows of the pages
still around it, with their lines and points as drawn, and reads and draws those of the
page that came near (240,000) in 0.2 s. With
page=, a level is read by its value (WHERE site IN (...)), not panel by panel.
- Lines, points and text are drawn from the plot's data a page at a time.
- Summaries (
hist,box,violin,density,smooth,errorbar) are computed by the database, every panel's at once, and no row is read: see below. selected()is a query of the selected rows, in every panel, not yet read: a DuckDB relation, an Ibis table or aLazyFrame. Read the rows when you need them (selected().pl(),.to_pandas(),.collect()), or count them first. A brush over a summary selects the rows it stands for: a histogram's bins, a box's group, a stretch of a curve.save_htmlandto_htmlread every row of the lines, points and text, asload="all"does: the page holds every panel. A plot of summaries only reads none.link=: a brush in a panel selects the rows sharing its rows' keys in every panel, as a query (selected()); the panels of the pages read light up those of the panel brushed.anytrellis.link(..., on=)links a plot reading pages to others by the values of columns (giveon=: its rows are in the database, not the same rows as another's). Its selection is read as the keys chosen; a selection elsewhere lights up the rows of the pages read, and the database counts the rows of the keys chosen that each summary stands for, every panel's in one query (a histogram's bars fill to their share). A page turned reads that page's rows only.- A wrap of 100 panels or fewer, which doesn't page, reads every row; give
rows=to page it. Withpage=, a page is a level: turning to it reads that level's rows (a grid's too). - A database that can't compute the panels' statistics (a median, a standard deviation)
gives an error: use
load="all". Without the trend's window query (Ibis, over a time x), the statistics have no trend.
Summaries from the database¶
A summary of the plot's data is a query or two, grouped by the facet columns (and the colour, and a box's positions), whose answer is a few rows per panel:
| Mark | What the database computes |
|---|---|
hist |
the count in each bin; the bins from the range of every row (min, max) |
box |
the quartiles (quantile_cont), the whiskers' ends, and the values beyond them |
errorbar |
each group's count, mean, standard deviation, lowest and highest value |
smooth(method="linear") |
each group's sums of squares and products about its means |
smooth() (loess) |
each group's values in 1,024 bins of x: their count and mean x, and the sum of y and of its squares; the local fits are made on the bins |
density, violin |
each group's values in fine bins, an eighth of its bandwidth wide (64 to 8,192 to a group); the curve is made from the bins |
They are made once, for every panel: the axes are those of every panel's summary from the start, and turning a page sends the next panels' without asking again. They are as they are from the rows read, except the curves made from bins: a density's or a violin's differs by about 0.03% of its peak, and a loess fit by a few thousandths of the scatter about it.
Ten million readings of 1,000 stations, from DuckDB:
| Mark | load="pages" |
load="all" |
|---|---|---|
hist(x="temp", color="sensor") |
0.8 s | 3.2 s |
box(x="sensor", y="temp") |
0.9 s | 4.6 s |
violin(x="sensor", y="temp") |
1.8 s | 8.4 s |
density(x="temp", color="sensor") |
1.5 s | 5.2 s |
smooth(x="time", y="temp", method="linear") |
0.7 s | 2.9 s |
smooth(x="time", y="temp") (loess) |
3.6 s | 22 s |
errorbar(x="sensor", y="temp") |
0.4 s | 4.4 s |
What the database doesn't summarise comes from the rows, read once (the columns the mark
draws, every panel's): a violin's points (inner="points"), error bars of given ends
(ymin=, ymax=), and, from Ibis, summaries of a time column (it has no times as
numbers).
Large tables¶
anytrellis reads only the columns a plot uses, once, and sends them to the browser as binary arrays. Text columns are encoded by PyArrow when it is installed: tens of times faster than labelling millions of rows one by one. See Plot large data.