Skip to content

Trellis

Trellis

Trellis(
    data: Any = None,
    *,
    row: str | Sequence[str] | None = None,
    col: str | Sequence[str] | None = None,
    wrap: str | Sequence[str] | None = None,
    cols: int | None = None,
    rows: int | str | None = None,
    page: str | Sequence[str] | None = None,
    share_x: bool | str = True,
    share_y: bool | str = True,
    x_scale: str = "linear",
    y_scale: str = "linear",
    height: int | None = None,
    panel_height: int | None = None,
    aspect: float | str | None = None,
    title: str = "",
    subtitle: str = "",
    caption: str = "",
    labels: Mapping[str, str] | None = None,
    x_title: str | None = None,
    y_title: str | None = None,
    palette: str
    | Sequence[str]
    | Mapping[str, str]
    | None = None,
    legend: str = "auto",
    strips: str = "nested",
    strip_label: str | None = None,
    empty: str = "draw",
    margins: bool | str = False,
    fit_y: bool = False,
    link: str | Sequence[str] | None = None,
    load: str = "all",
    theme: str | Theme | None = None,
    renderer: str = "auto",
)

A trellis of panels: one per level of the facet columns, each drawn with the same layers, on shared scales unless told otherwise.

from anytrellis import Trellis

t = Trellis(df, wrap="station")                  # or row="site", col="year"
t.line(x="time", y="temp", color="sensor")
t                                                # scroll to zoom: shared axes zoom together

Parameters:

  • data (Any, default: None ) –

    The table the layers draw (Polars, PyArrow, pandas, DuckDB, Ibis, or a dict of arrays). A layer may bring its own; a layer whose data lacks the facet columns is drawn in every panel. A lazy table (a Polars LazyFrame, a DuckDB relation, an Ibis table) is read in one query, with only the columns the plot uses, and computes the panels' summaries itself.

  • row (str | Sequence[str] | None, default: None ) –

    Facet column(s) whose levels are the grid's rows.

  • col (str | Sequence[str] | None, default: None ) –

    Facet column(s) whose levels are the grid's columns.

  • wrap (str | Sequence[str] | None, default: None ) –

    Facet column(s) whose levels are panels wrapped into cols columns (not with row or col).

  • cols (int | None, default: None ) –

    Columns of a wrap (default: about the square root of the panels; 6 a page).

  • rows (int | str | None, default: None ) –

    Rows of panels a page of a wrap shows: a wrap of more than 100 panels shows 4 at a time, and the reader turns the pages, sorts and filters the panels (by their statistics: see panel_stats). rows=3 pages any wrap; "all" never pages. With page: a page level with more panels than fit goes on several pages.

  • page (str | Sequence[str] | None, default: None ) –

    Column(s) whose levels are pages: each page shows one level's grid (row, col: the same rows and columns on every page) or wrap (its panels, sorted and filtered as any paged wrap's). The reader picks the page by its level.

  • share_x (bool | str, default: True ) –

    Share the x scale: True (all panels), "row", "col", "page" (the panels of a page of page), 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; zooming one zooms all to its width).

  • share_y (bool | str, default: True ) –

    The same for y.

  • x_scale (str, default: 'linear' ) –

    "linear" or "log" (log10: values of 0 or less are left out; a histogram's bins and a density are computed on the log scale).

  • y_scale (str, default: 'linear' ) –

    The same for y (not with marks drawn from zero: bars, areas, histograms, densities).

  • height (int | None, default: None ) –

    The plot's height in CSS pixels (default: from panel_height).

  • panel_height (int | None, default: None ) –

    Each panel's height in CSS pixels (default: from its width).

  • aspect (float | str | None, default: None ) –

    Each panel's height as a multiple of its width (1: square), or "bank": the one showing the lines' median slope at 45 degrees, where changes are easiest to compare (Cleveland's banking; the smooth() fits', or without them the line() layers'), unless height or panel_height is given (default: about 0.62, between 90 and 300 px).

  • title (str, default: '' ) –

    A title over the plot: what it shows, or better what it says.

  • subtitle (str, default: '' ) –

    A line or two under the title (what is plotted, the units, the period).

  • caption (str, default: '' ) –

    A note under the plot (the source, a footnote). Like the title and subtitle it is part of exported images.

  • labels (Mapping[str, str] | None, default: None ) –

    Names to show for columns, {"mpg": "Fuel use (mpg)"}: in the axis and legend titles, the tooltips, a page's title and the sort and filter menus (code still names columns as they are: pages(sort="mean mpg")).

  • x_title (str | None, default: None ) –

    The x axis title (default: the x column's label or name).

  • y_title (str | None, default: None ) –

    The y axis title (default: the y column's label or name).

  • palette (str | Sequence[str] | Mapping[str, str] | None, default: None ) –

    Colours for category colour columns: a list of colours, a name ("petroff10", "okabe-ito", "observable10", "tab10", ...; default: the theme's), or a dict giving categories their colours, {"Europe": "#1f77b4"}, so they keep them across plots (the others: the theme's colours that are left, in order). Number colour columns: colormap().

  • legend (str, default: 'auto' ) –

    "auto": in a wrap's empty cells after its last panel when it fits there, under the plot otherwise; "bottom": always under the plot; "right": in a column right of the plot (under it when too tall); "none": no legend. Also legend().

  • strips (str, default: 'nested' ) –

    With several facet columns, "nested": a strip per column, each spanning the panels of its level (the first column's outermost); "joined": one strip per panel, row or column naming its levels together ("north · A").

  • strip_label (str | None, default: None ) –

    A column whose value names each panel: every panel gets a strip of its own with it (a grid too), in place of the strips above. It must have one value per panel; a panel without one is named by its levels. Panel names in panels() and open() stay their levels.

  • empty (str, default: 'draw' ) –

    A grid's cells without data: "draw" (empty panels, so a missing combination shows) or "blank" (left out, the others in their rows and columns: a triangle stays a triangle). With page=: the cells without data on every page, so each page has the same cells.

  • margins (bool | str, default: False ) –

    A grid's "(all)" panels, each of the rows of several panels (as ggplot2's facet_grid(margins=TRUE)): "row", an (all) row under the rows, each panel the rows of its column; "col", an (all) column right of the columns, each panel the rows of its row; True, both and a corner of every row. Every layer draws them, summaries (hist, box, smooth, ...) computed of their rows.

  • fit_y (bool, default: False ) –

    Start with y fitted to the data in view: zooming or panning x refits each y scale (shared ones to all their panels), until y is zoomed by hand. The y key and the toolbar switch it on and off.

  • link (str | Sequence[str] | None, default: None ) –

    Column(s) that identify a thing across panels (a country, a station): a selection grows to every row sharing them, in all panels and layers that have the columns. Select a few countries in 1955 and see them in every year. (Separate plots sharing a selection: anytrellis.link.)

  • load (str, default: 'all' ) –

    How a lazy table's rows are read: "all" (every row, once) or "pages" (a paged wrap: only the rows of the panels of the page shown and the pages either side of it, read again as the reader turns the pages; the panels' statistics, the axes' ranges and the colours' levels come from the database). For a table in a database: lines, points and text drawn from the plot's data (other layers bring their own); not with link. save_html still reads every row.

  • theme (str | Theme | None, default: None ) –

    How the plot looks: "minimal", "framed", "classic", or an anytrellis.Theme changing any of their settings (default: "minimal", or what anytrellis.set_theme set). minimal: nothing behind the data but a faint grid (across y, and x for points), strips as titles at the left, the y title level over the plot ("↑ temp"), Petroff's colour-vision-tested palette. framed (after Observable Plot): a thin frame around each panel and more room between them, strips centred, the x title at its axis' end, d3's observable10. classic (the look before 0.6): grey panels and strips, a full grid, titles on their side, tab10. Every theme but classic leaves a time axis untitled unless x_title is given.

  • renderer (str, default: 'auto' ) –

    "auto" (WebGPU, then WebGL2, then Canvas 2D), or one of them.

focused property

focused: str | None

The opened panel's name (opened here or in the browser), or None.

pages property

pages: int

The number of pages, with the panels the filters keep (1 when it does not page).

page_names property

page_names: list[str]

Each page's name: its level of the page columns (page=), with "(2 of 3)" after it when the level has more pages; without page columns, "".

page property

page: int

The page shown, from 1.

paging property

paging: Paging

The page, sort and filters shown (set here or in the browser).

selection property

selection: dict[str, Any] | None

The selection (made here or in the browser): {"x": ..., "y": ..., "color": ..., "panel": ...}, each axis a (low, high) range (times as datetime64; a category axis: the categories in it) or None for any, the colours chosen in the legend (a list of categories) or None for any, and the panel it was drawn in (a linked plot) or None for all; None when nothing is selected.

widget property

widget: TrellisWidget

The widget that shows the plot: made the first time the plot is shown or this is read, then the same one.

line

line(
    data: Any = None,
    *,
    x: str,
    y: str,
    color: str | None = None,
    group: str | Sequence[str] | None = None,
    step: str | None = None,
    width: float = 1.5,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

Lines through the points of each series, sorted by x; or steps between them.

t = Trellis(gapminder, wrap="region")
t.line(x="year", y="life_expect", group="country", width=1)
t.line(x="time", y="state", step="post")    # each value holds until the next

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column.

  • y (str) –

    The y column.

  • color (str | None, default: None ) –

    A colour column (one line per category; numbers along a colormap) or one colour.

  • group (str | Sequence[str] | None, default: None ) –

    Column(s) whose combinations are separate lines (besides color).

  • step (str | None, default: None ) –

    Steps instead of slopes: "post" (each value holds until the next point: a level that changes at the points, as a counter or a state), "pre" (each value holds back to the point before) or "mid" (each holds to halfway between the points).

  • width (float, default: 1.5 ) –

    Line width in CSS pixels.

  • opacity (float, default: 1.0 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    "auto" (each row in its panel; every panel when the data has no facet columns), "include", "all" (every row in every panel) or "exclude" (each panel shows the other panels' rows: grey context).

  • tooltip (Sequence[str], default: () ) –

    Columns shown on hover, besides x and y.

  • name (str | None, default: None ) –

    The layer's name.

points

points(
    data: Any = None,
    *,
    x: str,
    y: str,
    color: str | None = None,
    size: float = 5.0,
    opacity: float = 0.85,
    jitter: float = 0.0,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

A point per row.

t = Trellis(penguins, wrap="species")
t.points(x="flipper_length_mm", y="body_mass_g", color="sex")
t.box(x="species", y="body_mass_g").points(x="species", y="body_mass_g", jitter=0.4)

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column.

  • y (str) –

    The y column.

  • color (str | None, default: None ) –

    A colour column or one colour.

  • size (float, default: 5.0 ) –

    Diameter in CSS pixels.

  • opacity (float, default: 0.85 ) –

    0 to 1.

  • jitter (float, default: 0.0 ) –

    Spread the points of a category axis across their band, up to this fraction of its width (0 to 1; 0.4 is a strip plot's), so points with the same value don't hide each other. Each row keeps its place from draw to draw.

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown on hover, besides x and y.

  • name (str | None, default: None ) –

    The layer's name.

bars

bars(
    data: Any = None,
    *,
    x: str,
    y: str,
    color: str | None = None,
    position: Position = "stack",
    width: float = 0.8,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

Bars from 0 to y at each x (categories, numbers or times); with a category y and x not, horizontal bars from 0 to x at each y.

Trellis(barley, wrap="site").bars(x="variety", y="yield", color="year", position="dodge")
Trellis(barley, wrap="site").bars(x="yield", y="variety", color="year")  # horizontal
Trellis(barley, wrap="site").bars(x="variety", y="yield", color="year", position="fill")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column (horizontal bars: their lengths).

  • y (str) –

    The bar heights (horizontal bars: a category column, their positions).

  • color (str | None, default: None ) –

    A colour column or one colour.

  • position (Position, default: 'stack' ) –

    With a category colour: "stack" (default), "fill" (stacked as shares of each stack, every stack as tall as 1: the composition, whatever the totals), "dodge" (side by side) or "identity" (overlapping).

  • width (float, default: 0.8 ) –

    Bar width as a fraction of the step between positions.

  • opacity (float, default: 1.0 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown on hover, besides x and y.

  • name (str | None, default: None ) –

    The layer's name.

area

area(
    data: Any = None,
    *,
    x: str,
    y: str,
    color: str | None = None,
    group: str | Sequence[str] | None = None,
    position: Position = "stack",
    opacity: float = 0.8,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

Filled areas under the line of each series, down to 0.

Trellis(by_region).area(x="year", y="pop", color="region")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column.

  • y (str) –

    The y column.

  • color (str | None, default: None ) –

    A colour column (one area per category) or one colour.

  • group (str | Sequence[str] | None, default: None ) –

    Column(s) whose combinations are separate areas (besides color).

  • position (Position, default: 'stack' ) –

    "stack" (default: each series on the ones before it, at equal x), "fill" (stacked as shares of the total at each x, up to 1) or "identity" (each from 0, overlapping).

  • opacity (float, default: 0.8 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown on hover, besides x and y.

  • name (str | None, default: None ) –

    The layer's name.

band

band(
    data: Any = None,
    *,
    x: str,
    ymin: str,
    ymax: str,
    color: str | None = None,
    group: str | Sequence[str] | None = None,
    opacity: float = 0.3,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

A band between two lines: from ymin to ymax along x (a range, an interval, an envelope), one per group (and colour).

Trellis(weather, wrap="year").band(x="date", ymin="temp_min", ymax="temp_max")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column.

  • ymin (str) –

    The lower line's column.

  • ymax (str) –

    The upper line's column.

  • color (str | None, default: None ) –

    A colour column or one colour.

  • group (str | Sequence[str] | None, default: None ) –

    Column(s) splitting the rows into separate bands.

  • opacity (float, default: 0.3 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown on hover, besides x, ymin and ymax.

  • name (str | None, default: None ) –

    The layer's name.

smooth

smooth(
    data: Any = None,
    *,
    x: str,
    y: str,
    color: str | None = None,
    method: str = "loess",
    se: bool = True,
    level: float = 0.95,
    span: float = 0.75,
    n: int = 80,
    fullrange: bool = False,
    width: float = 1.5,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    name: str | None = None,
) -> Self

A smooth line through each panel's points (and each colour's), with a confidence band for its mean.

t = Trellis(cars, wrap="origin")
t.points(x="horsepower", y="mpg").smooth(x="horsepower", y="mpg")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column (numbers or times).

  • y (str) –

    The y column.

  • color (str | None, default: None ) –

    A category column (a fit per category) or one colour.

  • method (str, default: 'loess' ) –

    "loess" (local linear regression, tricube weights) or "linear" (least squares).

  • se (bool, default: True ) –

    Draw the confidence band.

  • level (float, default: 0.95 ) –

    The band's confidence level.

  • span (float, default: 0.75 ) –

    Loess: the share of the points each local fit uses.

  • n (int, default: 80 ) –

    Points along each line.

  • fullrange (bool, default: False ) –

    Draw each line over every panel's x range, not its own data's.

  • width (float, default: 1.5 ) –

    Line width in CSS pixels.

  • opacity (float, default: 1.0 ) –

    0 to 1 (the band is lighter).

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • name (str | None, default: None ) –

    The layer's name.

rect

rect(
    data: Any = None,
    *,
    x: str,
    y: str,
    x2: str | None = None,
    y2: str | None = None,
    color: str | None = None,
    width: float = 1.0,
    height: float = 1.0,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

Rectangles: tiles centred on (x, y), one step of the data wide and high (a heatmap, with a number colour), or from (x, y) to (x2, y2).

Trellis(daily, wrap="year").rect(x="day", y="month", color="temp_max")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column (the tiles' centres, or their left with x2).

  • y (str) –

    The y column (centres, or bottoms with y2).

  • x2 (str | None, default: None ) –

    The tiles' right edges.

  • y2 (str | None, default: None ) –

    The tiles' tops.

  • color (str | None, default: None ) –

    A colour column or one colour (numbers: a colormap, as a heatmap).

  • width (float, default: 1.0 ) –

    A tile's width as a fraction of the step between x values.

  • height (float, default: 1.0 ) –

    A tile's height as a fraction of the step between y values.

  • opacity (float, default: 1.0 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown on hover, besides x and y (a number colour: shown).

  • name (str | None, default: None ) –

    The layer's name.

text

text(
    data: Any = None,
    *,
    x: str,
    y: str,
    text: str,
    color: str | None = None,
    size: float = 11.0,
    align: str = "center",
    dx: float = 0.0,
    dy: float = 0.0,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    name: str | None = None,
) -> Self

A label per row: the text column's value at (x, y).

t.text(x="fertility", y="life_expect", text="country", align="left", dx=6)

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The x column.

  • y (str) –

    The y column.

  • text (str) –

    The column of labels.

  • color (str | None, default: None ) –

    A colour column or one colour (default: the theme's text colour).

  • size (float, default: 11.0 ) –

    Font size in CSS pixels.

  • align (str, default: 'center' ) –

    "left", "center" or "right" of the point.

  • dx (float, default: 0.0 ) –

    Offset to the right, in CSS pixels.

  • dy (float, default: 0.0 ) –

    Offset down, in CSS pixels.

  • opacity (float, default: 1.0 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • name (str | None, default: None ) –

    The layer's name.

hist

hist(
    data: Any = None,
    *,
    x: str,
    color: str | None = None,
    bins: int | Sequence[Any] = 30,
    binwidth: Any = None,
    stat: str = "count",
    position: Position = "stack",
    width: float | None = None,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    name: str | None = None,
) -> Self

A histogram in each panel: the rows counted in bins that every panel shares.

Trellis(penguins, wrap="species").hist(x="flipper_length_mm", binwidth=2, color="sex")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The column binned (numbers or times); a category column: its categories counted.

  • color (str | None, default: None ) –

    A category column (its counts stacked or overlapping) or one colour.

  • bins (int | Sequence[Any], default: 30 ) –

    The number of bins over the values' range, or the edges.

  • binwidth (Any, default: None ) –

    A bin width instead (a time axis: a timedelta, or "7D", "6h"), the edges at its multiples.

  • stat (str, default: 'count' ) –

    "count", "percent" (of each panel's rows) or "density" (each panel's bars cover an area of 1).

  • position (Position, default: 'stack' ) –

    With a colour: "stack" (default), "fill" (each bin's colours as shares of it, up to 1) or "identity" (overlapping).

  • width (float | None, default: None ) –

    Bar width as a fraction of the bin (default 1; categories 0.8).

  • opacity (float, default: 1.0 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    As for line; "exclude": the other panels' histogram, in grey.

  • name (str | None, default: None ) –

    The layer's name.

box

box(
    data: Any = None,
    *,
    x: str,
    y: str,
    color: str | None = None,
    position: Position = "dodge",
    width: float = 0.8,
    whis: float = 1.5,
    outliers: bool = True,
    linewidth: float = 1.5,
    size: float = 4.0,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

Box plots: a box per position (and colour) in each panel, from the first to the third quartile with a line at the median, whiskers to the furthest values within whis times the box's height of it, and the values beyond as points.

Trellis(penguins, wrap="island").box(x="body_mass_g", y="species")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The positions (categories, or numbers), or the values for horizontal boxes.

  • y (str) –

    The values, or (a category column) the positions of horizontal boxes.

  • color (str | None, default: None ) –

    A category column (its boxes side by side) or one colour.

  • position (Position, default: 'dodge' ) –

    With a colour: "dodge" (default, side by side) or "identity".

  • width (float, default: 0.8 ) –

    Box width as a fraction of the step between positions.

  • whis (float, default: 1.5 ) –

    Whisker reach, in interquartile ranges (Tukey: 1.5).

  • outliers (bool, default: True ) –

    Draw the values beyond the whiskers.

  • linewidth (float, default: 1.5 ) –

    The box's outline, median and whiskers, in CSS pixels.

  • size (float, default: 4.0 ) –

    Outlier diameter in CSS pixels.

  • opacity (float, default: 1.0 ) –

    0 to 1 (the box's fill is lighter).

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown when hovering an outlier.

  • name (str | None, default: None ) –

    The layer's name.

density

density(
    data: Any = None,
    *,
    x: str,
    color: str | None = None,
    fill: bool = False,
    bw_adjust: float = 1.0,
    cut: float = 3.0,
    gridsize: int = 200,
    width: float = 1.5,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    name: str | None = None,
) -> Self

A density curve in each panel (and for each colour): a Gaussian kernel density estimate, each curve covering an area of 1, on x values every panel shares.

Trellis(penguins, wrap="species").density(x="body_mass_g", color="sex", fill=True)

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The column (numbers or times).

  • color (str | None, default: None ) –

    A category column (a curve per category) or one colour.

  • fill (bool, default: False ) –

    Fill the area under each curve too.

  • bw_adjust (float, default: 1.0 ) –

    The bandwidth, as a multiple of Scott's rule's.

  • cut (float, default: 3.0 ) –

    How far past the data each curve goes, in bandwidths.

  • gridsize (int, default: 200 ) –

    Points along the shared x grid.

  • width (float, default: 1.5 ) –

    Line width in CSS pixels.

  • opacity (float, default: 1.0 ) –

    0 to 1 (a fill is lighter).

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • name (str | None, default: None ) –

    The layer's name.

horizon

horizon(
    data: Any = None,
    *,
    x: str,
    y: str,
    bands: int = 3,
    origin: float = 0.0,
    step: float | None = None,
    name: str | None = None,
) -> Self

A horizon chart in each panel: a series in a short panel, its distance from origin cut into bands, each band laid over the one before in the panel's height and darker, blues above the origin and reds below it (folded up). A hundred series fit on a screen, and their highs and lows still show (Heer, Kong and Agrawala 2009).

Trellis(readings, wrap="station", cols=1, panel_height=24).horizon(
    x="time", y="temp", origin=10)

The y axis shows the height within a band; the legend names each band's range. Each panel draws one series: give each x one y. Margins (margins=) are left empty, since each has several panels' series.

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The column along the panel (numbers or times).

  • y (str) –

    The values (numbers).

  • bands (int, default: 3 ) –

    Bands on each side of the origin.

  • origin (float, default: 0.0 ) –

    The value the bands start from.

  • step (float | None, default: None ) –

    Each band's height in y's units (default: a round number, so the bands reach the farthest value from the origin in any panel; values past the last band fill it).

  • name (str | None, default: None ) –

    The layer's name.

violin

violin(
    data: Any = None,
    *,
    x: str,
    y: str,
    color: str | None = None,
    position: Position = "dodge",
    width: float = 0.8,
    scale: str = "area",
    inner: str | None = "quartiles",
    bw_adjust: float = 1.0,
    cut: float = 2.0,
    gridsize: int = 100,
    linewidth: float = 1.0,
    size: float = 3.0,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

Violins: the values' distribution at each position (and colour) in each panel, as their density mirrored around the position, with the median and quartiles inside. Where a box plot shows five numbers, a violin shows the shape: two peaks, a long tail.

Trellis(penguins, wrap="island").violin(x="species", y="body_mass_g")
Trellis(penguins).violin(x="body_mass_g", y="species", color="sex")  # horizontal

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str) –

    The positions (categories, or numbers), or the values for horizontal violins.

  • y (str) –

    The values, or (a category column) the positions of horizontal violins.

  • color (str | None, default: None ) –

    A category column (its violins side by side) or one colour.

  • position (Position, default: 'dodge' ) –

    With a colour: "dodge" (default, side by side) or "identity".

  • width (float, default: 0.8 ) –

    The widest violin's width, as a fraction of the step between positions.

  • scale (str, default: 'area' ) –

    "area" (every violin the same area), "count" (areas as the number of values) or "width" (every violin as wide).

  • inner (str | None, default: 'quartiles' ) –

    "quartiles" (the median across it, the quartiles half way), "points" (the values, along its middle) or None.

  • bw_adjust (float, default: 1.0 ) –

    The bandwidth, as a multiple of Scott's rule's.

  • cut (float, default: 2.0 ) –

    How far past the values each violin goes, in bandwidths.

  • gridsize (int, default: 100 ) –

    Points along each violin.

  • linewidth (float, default: 1.0 ) –

    The outline's (and the quartiles') width in CSS pixels.

  • size (float, default: 3.0 ) –

    The values' diameter in CSS pixels (inner="points").

  • opacity (float, default: 1.0 ) –

    0 to 1 (the fill is lighter).

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown when hovering a value (inner="points").

  • name (str | None, default: None ) –

    The layer's name.

errorbar

errorbar(
    data: Any = None,
    *,
    x: str | None = None,
    y: str | None = None,
    ymin: str | None = None,
    ymax: str | None = None,
    xmin: str | None = None,
    xmax: str | None = None,
    extent: str = "ci",
    level: float = 0.95,
    color: str | None = None,
    position: Position = "dodge",
    width: float = 0.8,
    cap: float = 0.25,
    points: bool = True,
    linewidth: float = 1.5,
    size: float = 6.0,
    opacity: float = 1.0,
    facet: FacetMode = "auto",
    tooltip: Sequence[str] = (),
    name: str | None = None,
) -> Self

Error bars: an interval at each position, with caps, and its centre as a point.

From the values: the mean of each position's (and colour's) values with an interval around it (extent). Or as given: from ymin to ymax at each x (xmin to xmax at each y: horizontal), centred on y (x) if given.

Trellis(penguins, wrap="island").errorbar(x="species", y="body_mass_g")  # mean, 95% CI
Trellis(fits, wrap="site").errorbar(x="dose", y="effect", ymin="lo", ymax="hi")

Parameters:

  • data (Any, default: None ) –

    The layer's table (default: the plot's).

  • x (str | None, default: None ) –

    The positions; or the values (a category y), or the centres (with xmin and xmax).

  • y (str | None, default: None ) –

    The values (a category or number x); or the centres (with ymin and ymax), or the positions (with xmin and xmax).

  • ymin (str | None, default: None ) –

    Each vertical bar's low end (with ymax).

  • ymax (str | None, default: None ) –

    Its high end.

  • xmin (str | None, default: None ) –

    Each horizontal bar's low end (with xmax).

  • xmax (str | None, default: None ) –

    Its high end.

  • extent (str, default: 'ci' ) –

    From the values: "ci" (the mean's level confidence interval), "se" (the mean ± its standard error), "sd" (± one standard deviation) or "range" (the lowest value to the highest). On a log axis, of the logs (the centre is the geometric mean).

  • level (float, default: 0.95 ) –

    The confidence level of extent="ci".

  • color (str | None, default: None ) –

    A category column (its bars side by side) or one colour.

  • position (Position, default: 'dodge' ) –

    With a colour: "dodge" (default, side by side) or "identity".

  • width (float, default: 0.8 ) –

    The room the bars of a position share (dodged), as a fraction of the step between positions.

  • cap (float, default: 0.25 ) –

    The caps' width, as a fraction of each bar's room: the step between positions, or its share of it when dodged (0: no caps).

  • points (bool, default: True ) –

    Draw the centre as a point.

  • linewidth (float, default: 1.5 ) –

    In CSS pixels.

  • size (float, default: 6.0 ) –

    The centre's diameter in CSS pixels.

  • opacity (float, default: 1.0 ) –

    0 to 1.

  • facet (FacetMode, default: 'auto' ) –

    As for line.

  • tooltip (Sequence[str], default: () ) –

    Columns shown on hover (bars as given).

  • name (str | None, default: None ) –

    The layer's name.

rule

rule(
    data: Any = None,
    *,
    x: Any = None,
    y: Any = None,
    color: str = "#6b7480",
    width: float = 1.0,
    dash: Sequence[float] = (),
    name: str | None = None,
) -> Self

Reference lines: vertical at x, or horizontal at y. A value or a list of values: across every panel. With a table, a column of it: a line per row, in the panel of its facet columns' values (a table without them: in every panel), so each panel can have its own target, mean or limit.

t.rule(y=0, color="#888888", dash=(4, 3))
targets = pl.DataFrame({"site": ["Crookston", "Morris"], "target": [40, 35]})
Trellis(barley, wrap="site").points(x="yield", y="variety").rule(targets, x="target")

Parameters:

  • data (Any, default: None ) –

    A table of the lines' positions (and the facet columns), or None.

  • x (Any, default: None ) –

    Position(s) of vertical lines; with data, its column of them.

  • y (Any, default: None ) –

    Position(s) of horizontal lines; with data, its column of them.

  • color (str, default: '#6b7480' ) –

    Their colour.

  • width (float, default: 1.0 ) –

    Line width in CSS pixels.

  • dash (Sequence[float], default: () ) –

    A dash pattern in pixels, e.g. (4, 3).

  • name (str | None, default: None ) –

    The layer's name.

share

share(
    x: bool | str | None = None, y: bool | str | None = None
) -> Self

Share scales across panels: True (all), "row", "col", "page", False (each panel its own) or "sliced" (each its own range, all as wide as the widest). Panels that share a scale also zoom together.

scale

scale(x: str | None = None, y: str | None = None) -> Self

The axes' scales: "linear" or "log" (as Trellis(x_scale=...)).

limits

limits(
    x: tuple[Any, Any] | None = None,
    y: tuple[Any, Any] | None = None,
) -> Self

The axes' ranges, (low, high), either end None for the data's own: t.limits(y=(0, None)) starts y at 0. Times as dates or datetimes (("2026-03-01", None)), a log axis's in its values. Zooming starts there and Reset comes back there. (None, None): the data's range again.

format

format(
    x: str | None = None,
    y: str | None = None,
    *,
    color: str | None = None,
) -> Self

How values are written on the axes, in tooltips and at a colour legend's ends: d3-format strings for numbers (",.0f": 1,235; ".1%": 12.3%; ".2s": 1.2k; "$,.2f"), strftime strings for times ("%b %Y": Mar 2026; "%-d %b": 2 Mar; "%H:%M"), in UTC as the axis is. "": the automatic labels again.

t.format(x="%b %Y", y=".0%")

legend

legend(
    position: str | None = None,
    *,
    title: str | Mapping[str, str] | None = None,
) -> Self

Where the legend goes, and its title.

Parameters:

  • position (str | None, default: None ) –

    "auto" (in a wrap's empty cells when it fits, else under the plot), "bottom", "right" (a column right of the plot; under it when too tall) or "none".

  • title (str | Mapping[str, str] | None, default: None ) –

    The colour legend's title (default: the colour column's label or name); with several colour columns, a dict by column.

as_category

as_category(*columns: str) -> Self

Read number columns as categories: their distinct values are the levels, in order (-10, -2, 3), labelled as numbers (4, not 4.0), rows without a value last. A colour then takes the palette's colours and a legend of the levels, an axis a band each, group= a series each, as a text column would.

t.as_category("cylinders").points(x="weight", y="mpg", color="cylinders")
t.as_category("cylinders").order("cylinders", [8, 6, 4])

order

order(
    column: str,
    levels: Sequence[Any] | None = None,
    *,
    by: Summary | None = None,
    of: str | None = None,
    descending: bool = False,
) -> Self

Order a category column's levels (a number column's too, read as categories: as_category): as levels lists them (the rest after), or by a summary of a column per level (Cleveland's ordering by the median, for one), rather than alphabetically. This orders panels (facet columns), bands on an axis and colours alike.

t.order("site", by="median", of="yield")
t.order("month", ["Jan", "Feb", "Mar"])

panels

panels() -> list[str]

The panels' names, in order: each panel's level of every facet column, joined by · ("north · s1" in a grid of region by sensor).

open

open(*panel: Any) -> Self

Show one panel alone, on the whole plot (as a double-click on it does): by its name (see panels()) or by its level of each facet column.

t.open("station 3")          # wrap="station"
t.open("north", "s1")        # row="region", col="sensor"

The zoom stays linked: back in the grid, the panels sharing its scales show what the opened panel showed. close() (or Backspace, Esc, a double-click) goes back.

close

close() -> Self

Back to all panels from an opened one.

panel_stats

panel_stats(data: Any) -> Self

Statistics of each panel, to sort and filter a paged wrap's panels by: a table with the facet columns and one row per panel; each other column is a statistic (numbers, or text). They join the ones the plot computes (rows, and the mean, median, min, max, sd and trend of the values drawn).

info = df.group_by("station").agg(pl.col("temp").quantile(0.9).alias("p90 temp"),
                                  pl.col("region").first())
t.panel_stats(info)

stats

stats() -> dict[str, list[Any]]

The panels' statistics, to sort and filter by: {name: [a value per panel]}, in the order of panels() (empty when the plot does not page).

sort_panels

sort_panels(
    by: str | None = None, *, descending: bool = False
) -> Self

Sort a paged wrap's panels by a statistic (a name from stats()), as the reader can in the browser; None: as given (order). Panels without a value go last.

t.sort_panels("trend temp", descending=True)   # the steepest rise first

filter_panels

filter_panels(name: str = '', **where: Any) -> Self

Show only the panels whose name has every word of name, and whose statistics are in the ranges given: (low, high) for numbers (None: open), a piece of text for text. filter_panels() shows them all again. A statistic's name with spaces goes in a dict: filter_panels(**{"mean temp": (20, None)}).

t.filter_panels("north")
t.filter_panels(rows=(100, None), region="Europe")

show_page

show_page(page: int | str) -> Self

Turn to a page: by number (from 1), or by its name (see page_names: a level of the page columns, the first of its pages).

t.show_page(3)
t.show_page("Amsterdam")      # page="site"

shown_panels

shown_panels() -> list[str]

The names of the panels on the page shown, in order (all panels when it does not page).

select

select(
    x: Any = None,
    y: Any = None,
    *,
    color: Any = None,
    panel: Any = None,
) -> Self

Select the marks in a range of x, of y or of both, as a brush drawn in the browser does: in every panel, or in panel alone (a name from panels(), or a tuple of its levels); with link, also every row sharing a key with them, in all panels. color: only the marks of these colours, as clicking legend entries does. select() clears the selection.

t.select(x=("2026-03-05", "2026-03-08"))   # a time axis: dates, datetimes
t.select(x=(2, 4), y=(60, 80))             # numbers
t.select(x=["Europe", "Asia"])             # a category axis: its categories
t.select(x=(0, 3), panel="1955")           # with link="country": follow them
t.select(color=["Asia", "Africa"])         # a colour column's categories

selected

selected(layer: str | int | None = None) -> Any

The selected rows of a layer's data (default: the first layer), as the same kind of table (Polars, pandas, PyArrow, ...); none selected: no rows. In a linked plot (anytrellis.link) without a brush of its own: the rows another plot selects.

to_html

to_html(*, title: str | None = None) -> str

The plot as a standalone HTML page: data and code inside, no kernel needed.

save_html

save_html(
    path: str | Path, *, title: str | None = None
) -> Path

Write to_html to a file; returns its path.

save_svg

save_svg(
    path: str | Path,
    *,
    width: float | None = None,
    height: float | None = None,
    theme: str = "light",
) -> Path

Write the plot as an SVG image, drawn in Python (no browser needed: a script, a CI job); returns its path. It is the plot as shown: the zoom it was last shown with, the selection and an opened panel, every mark, axis and label a vector element.

t.save_svg("temperatures.svg")
t.save_svg("slide.svg", width=1200, height=600, theme="dark")

Parameters:

  • path (str | Path) –

    The file to write.

  • width (float | None, default: None ) –

    The image's width in CSS pixels (default: the width the plot was last shown at, else 800).

  • height (float | None, default: None ) –

    The image's height in CSS pixels (default: as the plot lays out); panels with an aspect keep their shape within it.

  • theme (str, default: 'light' ) –

    "light" or "dark".

save_png

save_png(
    path: str | Path,
    *,
    width: float | None = None,
    height: float | None = None,
    theme: str = "light",
    scale: float = 2.0,
) -> Path

Write the plot as a PNG image, drawn in Python as save_svg draws it, with scale pixels per CSS pixel (2: sharp on slides and high-density screens); returns its path. Needs resvg-py: pip install "anytrellis[png]".

t.save_png("temperatures.png")
t.save_png("thumbnail.png", width=400, scale=1)

colormap

colormap(
    colormap: str | Sequence[str] | None = None,
    *,
    scale: str | None = None,
    midpoint: float | None = None,
    bins: int | None = None,
) -> Self

How number colour columns take their colours.

t.colormap("cividis")                              # another colormap
t.colormap(scale="diverging", midpoint=0)          # change from zero: RdBu, red high
t.colormap("Blues", scale="binned", bins=6)        # about six steps of round width
t.colormap(scale="quantile", bins=4)               # four steps, as many values each

Parameters:

  • colormap (str | Sequence[str] | None, default: None ) –

    "viridis" (the default), "cividis", "magma", "Blues", "RdBu", "PuOr", each reversed with "_r", or a list of colours, low to high.

  • scale (str | None, default: None ) –

    "linear" (the default): lowest to highest along the colormap; "diverging": both sides of midpoint equally deep, the colormap's middle at it (default colormap: "RdBu_r"); "binned": steps of round width, a colour each, read back from the legend's ranges; "quantile": steps holding as many values each.

  • midpoint (float | None, default: None ) –

    The value a diverging scale centres on (default 0).

  • bins (int | None, default: None ) –

    About how many steps a binned scale has, and how many a quantile one has (2 to 20, default 5).