Your first trellis plot¶
In this tutorial you split a table of cars into panels, look around in the plot, colour the cars by a column, add a fitted line, and save the plot as a page to share. It takes about ten minutes.
You need a notebook (JupyterLab, VS Code or marimo) with anytrellis and Polars installed:
pip install "anytrellis[examples]". See how to install anytrellis.
Type each step into a new cell and run it.
1. Get a table¶
anytrellis comes with a few small datasets. cars has 406 cars from the 1970s and early
1980s, one row per car:
from anytrellis import Trellis
from anytrellis.datasets import load
cars = load("cars")
cars.head()
| name | mpg | cylinders | displacement | horsepower | weight | acceleration | year | origin |
|---|---|---|---|---|---|---|---|---|
| str | f64 | i64 | f64 | i64 | i64 | f64 | i64 | str |
| "chevrolet chevelle malibu" | 18.0 | 8 | 307.0 | 130 | 3504 | 12.0 | 1970 | "USA" |
| "buick skylark 320" | 15.0 | 8 | 350.0 | 165 | 3693 | 11.5 | 1970 | "USA" |
| "plymouth satellite" | 18.0 | 8 | 318.0 | 150 | 3436 | 11.0 | 1970 | "USA" |
| "amc rebel sst" | 16.0 | 8 | 304.0 | 150 | 3433 | 12.0 | 1970 | "USA" |
| "ford torino" | 17.0 | 8 | 302.0 | 140 | 3449 | 10.5 | 1970 | "USA" |
2. A panel per group¶
A trellis plot splits a table into groups and draws the same plot for each one. Here,
wrap="origin" makes a panel per origin, and each panel draws the cars' weight against
their fuel use:
plot = Trellis(cars, wrap="origin")
plot.points(x="weight", y="mpg")
plot
The last line, plot, shows the plot below the cell. The three panels share their scales:
the same weight is at the same place in each, so you can compare the panels at a glance.
The axes are drawn only once, at the edges.
3. Look around¶
The plot above is live, like the one in your notebook. Try this:
- Click the plot, then scroll over a panel to zoom in on x. All three panels zoom together, because they share x. (Before a click, scrolling scrolls the page.)
- Drag to pan. Shift+scroll zooms y.
- Hover over a point to see its values, and a crosshair in every panel.
- Double-click a panel to see it alone. Press Page Down for the next one, and Backspace to go back to all of them.
- Press r to reset the zoom.
Mouse and keys lists everything the plot does.
4. Colour by a column¶
Give color= a column. A column of numbers, like cylinders, is drawn along a colour
scale; a column of text gets a colour per category. tooltip= adds columns to what
hovering shows:
plot = Trellis(cars, wrap="origin", title="Fuel use and weight, by origin")
plot.points(x="weight", y="mpg", color="cylinders", tooltip=["name", "year"])
plot
Hover over the lightest cars in the Japan panel: their names are in the tooltip.
5. Add a layer¶
Each method adds a layer, and every panel draws every layer, in the order you added them.
A smooth() layer fits a line to each panel's points, with a band for its uncertainty.
The methods return the plot, so you can chain them:
plot = (
Trellis(cars, wrap="origin", title="Fuel use and weight, by origin")
.points(x="weight", y="mpg", color="cylinders", tooltip=["name"])
.smooth(x="weight", y="mpg", color="#444444")
)
plot
In every origin, heavier cars use more fuel. At the same weight, European and Japanese cars went only a little further on a gallon than American ones: most of the difference between the origins is that the American cars were heavier.
6. Share it¶
save_html writes the plot, with its data, into one HTML file. It opens in any browser,
without Python, and zooms and hovers as it does here:
plot.save_html("cars.html")
What you learned¶
Trellis(table, wrap="column")makes a panel per level of a column.- Methods like
points()andsmooth()add layers that every panel draws. - Panels share their scales, and zoom together.
color=andtooltip=take columns.save_html()writes a page that opens without Python.
Next: Facets and scales shows grids of panels, and what to do when the panels' values are too different to share a scale.