Skip to content

Draw lines, points and bars

Each mark is a method that adds a layer, and every panel draws every layer, in the order you added them. The methods return the plot, so they chain.

Points

from anytrellis import Trellis
from anytrellis.datasets import load

penguins = load("penguins")
plot = Trellis(penguins, wrap="species", panel_height=170)
plot.points(x="flipper_length_mm", y="body_mass_g", color="sex", size=6, opacity=0.7,
            tooltip=["island"])
plot

size= is the diameter in pixels, opacity= from 0 to 1, and tooltip= adds columns to what hovering shows.

Lines

A line joins the rows of each series, sorted by x. color= makes a line per category; group= makes separate lines without colouring them:

gapminder = load("gapminder")
plot = Trellis(gapminder, wrap="region", cols=3, panel_height=120)
plot.line(x="year", y="life_expect", group="country", width=1, tooltip=["country"])
plot

group=["station", "sensor"] takes several columns: a line per combination.

Steps

step= draws a line as steps: flat between rows, then straight up or down. Use it for a value that holds until the next row (a price, a setting) or a total over each period, as each month's rain here, centred on its month:

import polars as pl

weather = load("seattle_weather")
monthly = weather.group_by(
    year=pl.col("date").dt.year().cast(pl.String), month=pl.col("date").dt.month()
).agg(pl.col("precipitation").sum())
plot = Trellis(monthly, wrap="year", cols=2, panel_height=120, y_title="rain (mm)")
plot.line(x="month", y="precipitation", step="mid")
plot
step= Each row's value
"post" from its x to the next row's
"pre" from the row before's x to its own
"mid" from half way to the row before to half way to the next

Hovering a step shows the row it starts from.

Bars

Bars go from zero to y at each x. With a category color=, they stack by default; position="dodge" puts them side by side, and "identity" overlaps them:

import polars as pl

barley = load("barley").with_columns(pl.col("year").cast(pl.String))
plot = Trellis(barley, wrap="site", cols=3, panel_height=140)
plot.bars(x="variety", y="yield", color="year", position="dodge")
plot

The years are cast to text so they are categories (two colours), not numbers (a colour scale). width= sets a bar's width as a share of the step between x values.

Bars along y

When y is a category column and x is not, the bars lie along y, from zero to x. Long category names then read across, and ranked bars read from the top:

plot = Trellis(barley, wrap="site", cols=3, panel_height=170)
plot.bars(x="yield", y="variety", color="year")
plot

Shares: position="fill"

position="fill" stacks the colours as shares of each stack, so every stack reaches 1 and the composition compares across positions and panels, whatever their totals. The axis reads in percent (format(y=...) changes it):

plot = Trellis(barley, wrap="site", cols=3, panel_height=140)
plot.bars(x="variety", y="yield", color="year", position="fill")
plot

area() and hist() take position="fill" too: each region's share of the population at each year, each sex's share of each bin.

Bars count nothing themselves: to count rows, use a histogram, or count with your table library first (df.group_by(...).len()).

Several layers

Layers draw in order, so add the background first:

from anytrellis.synthetic import sensors

readings = sensors(stations=4, sensors=2, hours=24 * 7)
plot = (
    Trellis(readings, wrap="station", cols=2, panel_height=130)
    .line(x="time", y="temp", color="sensor", width=1)
    .points(x="time", y="temp", color="sensor", size=2)
    .rule(y=0, color="#888888", dash=(4, 3))
)
plot

rule() draws reference lines across every panel, rule(y=0), rule(x=[1960, 1980]), or each panel's own from a table (see Reference lines). Each layer gets a name (points, line, ...) for selected("line"); name= sets your own.

Each group against the rest

facet="exclude" draws, in each panel, the other panels' rows, in grey: each group seen against all the others.

plot = (
    Trellis(gapminder, wrap="region", cols=3, panel_height=120,
            title="Life expectancy, each region against the rest")
    .line(x="year", y="life_expect", group="country", facet="exclude", width=1, name="others")
    .line(x="year", y="life_expect", group="country", color="region", tooltip=["country"])
)
plot
facet= Each panel draws
"auto" (default) its own rows; every row when the layer's table has no facet columns
"include" its own rows
"all" every row
"exclude" the other panels' rows, in grey; never selected