Skip to main content

anytrellis

PyPI CI Docs

Trellis, facet and small-multiple plots for Jupyter and marimo notebooks, drawn on the GPU (WebGPU, WebGL2, or Canvas 2D on machines without a usable GPU).

Documentation: mluttikh.github.io/anytrellis: tutorials, guides, a gallery and the API reference, with live plots.

pip install anytrellis
pip install "anytrellis[examples]"   # with Polars, for the example notebooks and datasets
pip install "anytrellis[png]"        # with resvg-py, for save_png

Status: early development (0.6). One panel per level of the facet columns, every panel drawn with the same layers (lines, points, bars, areas, rects, text, histograms, box plots, violins, densities, error bars, reference rules), on shared scales unless told otherwise. Every panel goes into one canvas, so a grid of hundreds of panels and millions of marks stays interactive; long lines and dense points go to the browser at the level of detail its pixels need, and in more as you zoom in.

from anytrellis import Trellis
from anytrellis.synthetic import sensors

df = sensors()  # a dict of columns; any Polars, pandas or PyArrow table works too
t = Trellis(df, wrap="station")
t.line(x="time", y="temp", color="sensor")
t.rule(y=0)
t  # click it, then scroll to zoom; panels that share a scale zoom together

A grid crosses two facet columns, and keeps empty cells so rows and columns stay aligned:

from anytrellis.synthetic import sales

Trellis(sales(), row="store", col="product").bars(x="month", y="units")

Marks

Each mark is a method that adds a layer; layers draw in the order they were added.

method draws
line(x, y, color, group, step=None|"post"|"pre"|"mid") a line per group (and colour), or steps
points(x, y, color, size) a point per row
bars(x, y, color, position="stack"|"dodge"|"identity") a bar per row, from zero
area(x, y, color, group, position="stack"|"identity") the area under a line, stacked like bars
band(x, ymin, ymax, color, group) a band between two lines (a range, an interval)
rect(x, y, color, width=1, height=1) / rect(x, y, x2=, y2=) a cell per row (a heatmap), or a box between two corners
text(x, y, text, color, size, align, dx, dy) a label per row
rule(x=..., y=...) reference lines across every panel
hist(x, color, bins=30 | binwidth=, stat="count"|"percent"|"density") a histogram per panel, stacked by colour
box(x, y, color, whis=1.5) box plots per position (and colour, side by side); sideways when y is the category
violin(x, y, color, scale="area"|"count"|"width", inner="quartiles") violins per position, placed like boxes
density(x, color, fill=False, bw_adjust=1) a kernel density curve per panel and colour
errorbar(x, y, color, extent="ci"|"se"|"sd"|"range") / errorbar(x, ymin=, ymax=) a mean and its interval per position, or intervals you computed
smooth(x, y, color, method="loess"|"linear", se=True) a fitted line per panel and colour, with a confidence band
horizon(x, y, bands=3, origin=0, step=None) a horizon chart per panel: a series in bands, for many series in little height

A number column as color gets a continuous scale (and a gradient legend); text gets a palette. On a category axis a rect is one band wide by default. A text label's dx/dy are pixels, so labels keep their distance while zooming, and a label that would run past the panel's edge goes to the other side of its point. tooltip=[...] adds columns to what hovering shows (a box: to its outliers'); every mark but text and rule can be selected.

hist, box, violin, density, errorbar and smooth summarise each panel's rows in Python, and are drawn as bars, boxes, violins, lines, bands and points. A histogram's bins are the same in every panel (round widths by default), and so are a density's x values, so the panels compare. stat="percent" and "density" scale each panel's counts. With facet="exclude" a summary covers the other panels' rows, in grey: each panel against the rest. Hovering a box shows its quartiles, its count and its whiskers' reach; a smooth line, its confidence interval. smooth fits loess (local lines with tricube weights over a span share of the points) or least squares, and its band is the level (95%) interval for the mean. Brushing selects whole bins, boxes and violins, and t.selected("hist") gives the rows they stand for.

Every pair of columns

from anytrellis import pairs

p = pairs(penguins, ["bill_length_mm", "bill_depth_mm", "body_mass_g"], color="species")
p.selected()   # brush any panel: its rows light up in every panel, and come back as rows

pairs() is a scatterplot matrix: x by column and y by row, each variable's scale shared along its column and its row, and each variable alone on the diagonal (diag="density", "hist" or None). corner=True keeps each pair once.

Tables in a database

import duckdb

rel = duckdb.sql("select * from 'readings.parquet'")
t = Trellis(rel, wrap="station", load="pages")
t.line(x="time", y="temp").smooth(x="time", y="temp")
t.selected()   # after a brush: a query of the rows selected, not yet read

A Polars LazyFrame, a DuckDB relation or an Ibis table is read in one query, with only the columns the plot uses. With load="pages", a wrap of many panels reads only the rows of the page shown and the pages either side of it, as the pages turn; the panels, their statistics, the axes' ranges and the summaries (hist, box, violin, density, smooth, errorbar) come from the database, so every page looks as it would with every row read. Ten million rows in 1,000 panels from DuckDB draw in 1 s.

Facets and scales

  • Trellis(df, row=..., col=...): a grid; Trellis(df, wrap=..., cols=4): a wrap. Each takes one column or several (their combinations are the levels).
  • Several facet columns get nested strips, the first outermost, each spanning the panels that share its level (as ggh4x's); strips="joined" shows one strip per panel.
  • empty="blank": a grid's cells without data left out, the others in place (a triangle stays a triangle); strip_label="title": each panel named by a column, in a strip of its own; margins=True: a grid's "(all)" row and column, each panel the rows of its column or row ("row" or "col": one of them).
  • page="site": a page per level of a column, each a grid or a wrap of its own.
  • aspect=1: square panels (each panel's height as a multiple of its width); aspect="bank": the shape that shows the lines' median slope at 45 degrees (banking).
  • share_x= / share_y= (or t.share(x=..., y=...)): True (all panels, the default), "row", "col", 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). Axes are drawn only where a panel's scale differs from its neighbour's.
  • x_scale="log" / y_scale="log" (or t.scale(y="log")): a log10 scale, with ticks at decades (and 2 and 5 between when they fit). Values of 0 or less are left out; marks drawn from zero (bars, areas, histograms, densities) don't go on a log y. Summaries are computed on the log scale, as in ggplot2: a histogram's bins are equally wide on it.
  • t.order("site", by="median", of="yield"): panels ordered by a summary of each level.
  • t.order("month", ["Jan", "Feb", ...]): any category column in the given order: panels, bands on an axis and colours. Text is sorted otherwise; a pandas Categorical or a Polars Enum keeps its declared order.
  • line(..., group=["station", "sensor"]): one line per combination of the columns.
  • t.as_category("cylinders"): a number column as categories (a colour per value, a band per value on an axis), its values in order.
  • A layer whose data lacks the facet columns is drawn in every panel; facet="exclude" draws, in each panel, the other panels' data (grey context behind it).

A wrap whose last row is not full shows its legend in the empty cells there when it fits, and under the plot otherwise (also while one panel is open); Trellis(..., legend="bottom") keeps it under the plot.

Interaction

Click the plot, then: scroll to zoom x (Shift + scroll: y), drag to pan, r to reset. Zoom and pan apply to every panel that shares the scale. Hovering shows the nearest mark's values and a crosshair across the panels that share x.

One axis. Over an axis, scrolling zooms that axis alone and dragging pans it; double-clicking it resets it. An axis stands for its whole scale: with share_y="row" the left axis of a row zooms that row.

Box zoom. Shift+drag draws a box (or switch plain drag to it: z, or the toolbar). The box follows the drag: mostly sideways zooms x alone, mostly up or down y alone, otherwise both. While you draw it, the panels it will also zoom show where.

Fit y. y (or the toolbar) fits every y scale to the data in view, and keeps fitting it as you zoom or pan x; a shared y fits all its panels together, so they stay comparable. Zooming y by hand stops it. Trellis(..., fit_y=True) starts with it on.

u (or Cmd/Ctrl+Z) undoes a zoom, one step at a time.

Selecting. s (or the toolbar) makes drag a brush, shaped like a zoom box: x, y or both. It selects the marks it meets, in every panel, and the rest fade: the same range compared across panels. Drag the brush to move it; a click or Esc clears it.

Click a colour's entry in the legend to select its marks (Shift, Cmd or Ctrl+click adds or removes more; a click on the only one chosen clears). With a brush too, a mark must meet both: brush a range, then pick a colour in it. Marks coloured by another column, or by none, fade.

With Trellis(..., link="country") the brush selects in the panel you draw it in, and then every row sharing its link values, in all panels and layers that have the column: brush countries in 1955 and follow them through the years. From Python:

t.select(x=(2, 4), y=(60, 80))          # a time axis: dates; a category axis: categories
t.select(x=(0, 3), panel="1955")        # in one panel (with link: then followed)
t.select(color=["Asia", "Africa"])      # the legend's entries: these colours' marks
t.selection                             # {"x": (2, 4), "y": (60, 80), "color": None, "panel": None}
t.selected()                            # the selected rows, as the table you gave
t.select()                              # clear

A brush drawn in the browser reaches Python when you let go, so t.selected() in the next cell gives its rows. A point is selected inside the brush, a line or area segment with either end inside, a bar or rect overlapping it, a box when its body or lines are met; grey context is never selected.

Linked plots. link(a, b, ...) gives plots one selection (crossfiltering): brush in one and the others show the same rows, following the brush as it moves. Points and lines of those rows stay bright and 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. A brush in another plot of the link replaces the first; a click or Esc in any of them clears it.

from anytrellis import link

scatter = Trellis(cars).points(x="weight", y="mpg")
power = Trellis(cars).hist(x="horsepower")
link(scatter, power)                     # the same table: the same rows
link(by_year, lives, on="country")       # any tables: the rows sharing a country
power.selected()                         # the rows the link's selection picks

Without on=, the plots must draw the same table (the same object): a filtered copy is another table, so link it on= a key column. Python relays the selection, so the plots are linked while the kernel runs, not in a page from save_html. unlink() the returned link to set them apart.

One panel at a time. Double-click a panel (or press Enter over it) to see it alone on the whole plot; Page Up and Page Down (or ‹ ›) step to the previous and next panel at the same zoom, and Backspace, Esc, a double-click or All panels goes back. The zoom stays linked: back in the grid, the panels that share its scales show what the opened one showed. From Python: t.open("station 3") (a grid's panel: t.open("north", "s1")), t.close(), t.focused, and t.panels() lists the names.

Many panels. A wrap of more than 100 panels shows them a page at a time (6 by 4; rows= and cols= set it, rows="all" turns it off), with a bar to turn the pages (‹ ›, Page Up and Page Down), sort the panels by a statistic of each (rows, mean, median, min, max, sd and trend of the values drawn, plus any given with t.panel_stats(table)), filter them by name and by a statistic's range. The strips show the value sorted by. From Python: t.sort_panels("trend temp", descending=True), t.filter_panels("north"), t.show_page(2), t.shown_panels(); images and saved pages show the page shown.

Images. The toolbar's Export button (or e) copies the plot as shown, its zoom, selection and theme, to the clipboard as a PNG (or as an SVG with a PNG beside it, where the browser allows), downloads it as a PNG (at twice the screen's size) or an SVG, or, in a notebook, saves either next to the notebook. The toolbar and what the pointer points at are left out. From Python, without a browser (a script, a CI job), t.save_png("plot.png") and t.save_svg("plot.svg") draw the same: the zoom last shown, the selection and an opened panel (width=, height=, theme="dark"; PNGs need the png extra).

Full screen. The toolbar's button or f shows the plot on the whole screen (f or Esc leaves). Browsers allow it only from a click or a key, so not from Python; where a page forbids it (some notebook frames, iPhone Safari) the button is not shown.

key
f full screen, and back
e the Export menu: copy or download a PNG or SVG
r, 0 reset the zoom
u, Cmd/Ctrl+Z undo the last zoom
z drag draws a zoom box, and back (Shift+drag: the other)
y fit y to the data in view, and stop
s drag draws a selection brush, and back
Esc clear the selection (else: back to all panels)
click a legend entry select its colour (Shift+click: add or remove one)
Enter open the panel under the pointer
Page Up / Page Down previous / next panel (with none opened: page)
Backspace back to all panels
? the keys and mouse, the renderer and the version

These keys stay in the plot, so JupyterLab's own shortcuts don't also act on them.

Sharing

t.save_html("plot.html") writes a page with the data inside, which opens without Python.

Licence: MIT.

Examples

Notebooks in examples/jupyter (JupyterLab, VS Code) and the same in examples/marimo (marimo edit examples/marimo/01_getting_started.py):

notebook what it shows
01_getting_started wrap, grid, free scales, layers and context, rule, order, save_html
02_lattice_and_cleveland Cleveland's barley dot plot, Anscombe's quartet, conditioning on two variables, small multiples instead of an animation, following countries with linked brushing
03_ggplot2_style facet_wrap, facet_grid, gghighlight, scales = "free_y", stacked and dodged bars
04_seaborn_style relplot (scatter and line, col_wrap), FacetGrid histograms, catplot(kind="bar")
05_vega_lite_style row / column / facet channels, resolve_scale, a trellis of grouped bars
06_large_data a million points, a year of hourly readings, a hundred panels
07_linked_plots crossfiltering a scatter, histograms and boxes; plots linked by a key column

Their data comes with the package: from anytrellis.datasets import load; load("barley") (anscombe, barley, cars, gapminder, penguins, seattle_weather; from the UCI Machine Learning Repository and vega-datasets; their sources and licences are in SOURCES.md; the gapminder data is based on free material from GAPMINDER.ORG, CC-BY LICENSE). The notebooks are written once in scripts/build_examples.py, which writes both sets: run uv run python scripts/build_examples.py after changing it.

Development

uv sync                                    # builds js/ into src/anytrellis/static
uv run pytest                              # Python: spec, geometry, scales, protocol
cd js && npm test && npm run typecheck     # TypeScript: ticks, layout, picking
npm run build                              # after changing js/src
node test/visual.mjs <dir of save_html pages>      # screenshots per backend
node test/interact.mjs <page.html>                 # hover, linked zoom, pan, reset, dark
node test/zoom.mjs <page.html>                     # one axis, box zoom, fit y, undo
node test/select.mjs <page.html> [dir] [renderer]  # brushing, moving, clearing
node test/legend.mjs <page.html> [dir] [renderer]  # clicking legend entries
node test/toolbar.mjs <page.html> [dir] [renderer] # drag modes, state chips, the ? help
node test/export.mjs <page.html> [dir] [renderer]  # the Export menu: PNG, SVG, clipboard
node test/details.mjs <dir of pages> [dir] [renderer] # page styles, a partly selected histogram
node test/notebooks.mjs jupyter|marimo <url> <out> # a live notebook: run it, screenshot plots
node test/linked.mjs <url of 07 in JupyterLab>     # linked plots: brushing across plots
node test/live-detail.mjs <notebook url> [prefix] [chromium] # level of detail, live

Pages force a backend with ?renderer=webgpu|webgl2|canvas2d in their URL; uv run python js/test/pages.py <dir> writes the pages the browser checks run on.

The documentation is in docs/user/ (Markdown, built by Zensical with the settings in zensical.toml); its example plots run when it is built, and are live in the pages:

uv run python scripts/build_docs.py            # into site/; warnings fail the build
uv run python scripts/build_docs.py serve      # preview at http://localhost:8000
uv run python scripts/docs_gallery.py          # redraw the gallery's pictures (Chromium)

Build the JavaScript bundle first (cd js && npm run build). The build also fails on a page over 3 MB gzipped, and on a public method or parameter that no guide uses.

CI (.github/workflows/ci.yml) runs on every push to main and every pull request: ruff and ty, the TypeScript checks, pytest on Python 3.12 to 3.15 (Linux; macOS and Windows on 3.15), the select, legend, zoom and export checks in headless Chromium (WebGL2 and Canvas 2D); it builds the documentation (kept as the run's github-pages artifact), and builds the sdist and wheel, checked by scripts/check_dist.py (contents, version, a clean install that draws a plot).

Releasing

Releases go to PyPI from GitHub Actions by trusted publishing: no API token is stored.

Once, before the first release:

  1. On pypi.org, add a pending publisher: project anytrellis, owner mluttikh, repository anytrellis, workflow release.yml, environment pypi. For dry runs, do the same on test.pypi.org with environment testpypi.
  2. On GitHub (Settings > Environments), the environments pypi and testpypi; giving pypi a required reviewer makes every release wait for an approval.
  3. For the documentation: Settings > Pages > Source: GitHub Actions; then in Settings > Environments > github-pages, add the tag rule v* to the deployment branches and tags, so a release may deploy.

Each release:

  1. Set the version in pyproject.toml, and in CHANGELOG.md move Unreleased under a heading ## [x.y.z] - date (and update the links at the bottom).
  2. Optionally, a dry run: Actions > Release > Run workflow publishes to TestPyPI (pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ anytrellis).
  3. Commit, tag and push: git tag vx.y.z && git push origin main vx.y.z. The release workflow runs CI on the tag, checks that the tag matches the version, publishes to PyPI makes a GitHub release with the changelog's section and the files, and deploys the documentation. To fix a page between releases, run Actions > Docs > Run workflow.

Metadata

Release files for anytrellis 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anytrellis 0.6.0
File Size Uploaded Provenance Actions
anytrellis-0.6.0.tar.gz 520.7 kB With provenance Details for anytrellis-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anytrellis 0.6.0
File Interpreter ABI Platform Actions
anytrellis-0.6.0-py3-none-any.whl Python 3 none any Details for anytrellis-0.6.0-py3-none-any.whl

Total release size: 817.3 kB

Release files / anytrellis-0.6.0.tar.gz

Download URL anytrellis-0.6.0.tar.gz
Size 520.7 kB
Tags Source
SHA-256 checksum
How to use checksums
603a670280f4e93e6909a9a9b1149ebe2d2de6eeb1a7b3f6ff88297f4d93b40b
BLAKE2b-256 checksum
How to use checksums
5086b7501f4c11c481927a9dd8d8cb9a0cccff851981eeb9666c4ada5ba7689c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / anytrellis-0.6.0-py3-none-any.whl

Download URL anytrellis-0.6.0-py3-none-any.whl
Size 296.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9c971c25c399fddfc6de280efdd22687449815fa2101c8337f4fc525ede34365
BLAKE2b-256 checksum
How to use checksums
03e852ba412bafe0704210c97c8b80ba9fe6a0febb75c077af67687749b49ce8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for anytrellis 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anytrellis-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page