Skip to content

Link plots

link(a, b, ...) gives separate plots one selection: brush marks in one, and the others show the same rows. Points and lines of those rows stay bright while the rest fade, a histogram's bars fill to the share of their count that is selected, and a box lights up when any of its rows is. This is often called crossfiltering.

Linking needs a running notebook

Python passes the selection from plot to plot, so plots are linked while the kernel runs: in JupyterLab, VS Code or marimo, not on this page or in a page from save_html. The plots below are live on their own; the Python results were made when the page was built. Run the linked plots notebook to try it.

Plots of one table

Plots of the same table (the same object) select the same rows:

from anytrellis import Trellis, link
from anytrellis.datasets import load

cars = load("cars").drop_nulls(["mpg", "horsepower"])
scatter = Trellis(cars, panel_height=240, title="Weight and mileage")
scatter.points(x="weight", y="mpg", color="origin", size=5, tooltip=["name"])
power = Trellis(cars, wrap="origin", cols=3, panel_height=130, title="Horsepower")
power.hist(x="horsepower", binwidth=10)

link(scatter, power)
scatter

In a notebook, brush the heaviest cars in the scatter (s, then drag): the histograms fill to the share of each bin those cars make up. A selection made in Python reaches the other plots the same way, and selected() on any plot of the link gives the rows the link's selection picks:

scatter.select(x=(4000, 5200))
print(power.selected().select("name", "horsepower", "weight").head())
shape: (5, 3)
┌───────────────────┬────────────┬────────┐
│ name              ┆ horsepower ┆ weight │
│ ---               ┆ ---        ┆ ---    │
│ str               ┆ i64        ┆ i64    │
╞═══════════════════╪════════════╪════════╡
│ ford galaxie 500  ┆ 198        ┆ 4341   │
│ chevrolet impala  ┆ 220        ┆ 4354   │
│ plymouth fury iii ┆ 215        ┆ 4312   │
│ pontiac catalina  ┆ 225        ┆ 4425   │
│ ford f250         ┆ 215        ┆ 4615   │
└───────────────────┴────────────┴────────┘

A brush in another plot of the link replaces the first one, and a click or Esc in any of them clears it. The brush updates the others as it moves.

Plots of different tables: on=

A filtered copy, or a table of other things, is not the same table. Link it by a key column with on=: selecting rows then selects every row sharing their key, in all the linked plots.

gapminder = load("gapminder")
years = Trellis(gapminder, wrap="year", cols=6, panel_height=100, link="country",
                title="Fertility and life expectancy")
years.points(x="fertility", y="life_expect", color="region", size=4, tooltip=["country"])
lives = Trellis(gapminder, panel_height=220, title="Life expectancy")
lives.line(x="year", y="life_expect", color="region", group="country", tooltip=["country"])

link(years, lives, on="country")
years
years.select(x=(7, 9), panel="1955")
print(sorted(lives.selected()["country"].unique()))
['Afghanistan', 'Costa Rica', 'Dominican Republic', 'Iran', 'Iraq', 'Kenya', 'Philippines', 'Rwanda', 'Saudi Arabia']

link="country" on years follows the brushed countries through its own panels; on="country" shows the same countries in lives.

A plot reading a database a page at a time (load="pages", see tables) links with on= only: its rows are in the database. Its selection is read as the keys chosen, and a selection elsewhere lights up the rows of its pages read; its histograms fill to the share of the keys chosen, counted by the database.

link() returns a Link. unlink() sets the plots apart again (each keeps its own brush), and clear() clears the selection in all of them:

connection = link(scatter, power)
connection.clear()
connection.unlink()

A plot is in one link at most. See link and Link.