Skip to content

Colours, legends and order

One colour, or a colour per value

color= takes a column or one colour:

color= Draws
a text or category column a colour per category, from the palette, with a legend
a number column a colour scale (a colormap), with a gradient legend
a hex colour ("#d62728", "#888", or with alpha "#d6272880") every mark of the layer in it
from anytrellis import Trellis
from anytrellis.datasets import load

cars = load("cars")
plot = Trellis(cars, wrap="origin", cols=3, panel_height=170)
plot.points(x="weight", y="mpg", color="year", size=5, tooltip=["name"])
plot

A number column you mean as categories (years, cylinder counts) gets a colour scale. as_category() reads it as categories: a colour per value, from the palette, with a legend of the values in order:

plot = Trellis(cars, wrap="origin", cols=3, panel_height=170).as_category("cylinders")
plot.points(x="weight", y="mpg", color="cylinders", size=5, tooltip=["name"])
plot

The values are the levels, in order (3, 4, 5, 6, 8; negative numbers first), labelled as numbers (4, not 4.0), rows without one last as (missing). The column is categories everywhere in the plot: an axis gets a band per value, group= a series per value, and order("cylinders", [8, 6, 4]) orders them. With a database (load="pages"), the database finds the values and selects by them.

A palette

palette= gives the category colours, in the order of the categories:

import polars as pl

kinds = ["sun", "fog", "drizzle", "rain", "snow"]
months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split()
monthly = (
    load("seattle_weather")
    .group_by("weather", year=pl.col("date").dt.year(), month=pl.col("date").dt.strftime("%b"))
    .agg(days=pl.len())
)
plot = (
    Trellis(monthly, wrap="year", cols=2, panel_height=130, title="Seattle weather",
            palette=["#e7ba52", "#c7c7c7", "#aec7e8", "#1f77b4", "#9467bd"])
    .order("month", months)
    .order("weather", kinds)
    .bars(x="month", y="days", color="weather")
)
plot

palette= also takes a name:

Name Colours
"petroff10" (the default), "petroff8", "petroff6" Petroff's, chosen to stay apart for readers with colour-vision deficiency and ranked by a survey of what people prefer; the first are the farthest apart, so a plot with few categories gets the most distinct ones
"okabe-ito" Okabe and Ito's eight, made for colour-vision deficiency (black last)
"observable10" Observable Plot's, the framed theme's
"tab10" Tableau's ten, the default before and the classic theme's

Rows whose category is missing get a (missing) colour of their own.

Keep a category's colour

The palette's colours go to the categories in order, so a category's colour depends on which others are in the plot. A dict gives categories their own, the same in every plot that has them; the other categories take the palette's colours that are left:

plot = Trellis(cars, wrap="cylinders", cols=5, panel_height=150,
               palette={"USA": "#d62728", "Europe": "#1f77b4"})
plot.points(x="weight", y="mpg", color="origin", size=5)
plot

Number colours: colormap()

A number colour column runs along viridis, lowest to highest. colormap() picks another colormap and how the values take it:

plot.colormap("cividis")                         # another colormap
plot.colormap(["#ffffff", "#d62728"])            # your own, low to high
plot.colormap(scale="diverging", midpoint=0)     # change from zero
plot.colormap("Blues", scale="binned", bins=6)   # steps of round width
plot.colormap(scale="quantile", bins=4)          # four steps, a quarter of the values each

The colormaps are "viridis", "cividis" (also for colour-vision deficiency) and "magma", dark to light; "Blues", one hue; and "RdBu" and "PuOr", which diverge from a light middle. "_r" reverses any of them ("viridis_r").

A diverging scale puts the colormap's middle at midpoint= and goes as deep on both sides, so equal distances above and below look equally strong; the side with less range doesn't reach its end. Its default is "RdBu_r", red above the midpoint:

gap = load("gapminder")
change = gap.with_columns(gap=pl.col("life_expect") - pl.col("life_expect").mean())
plot = Trellis(change, wrap="year", cols=4, panel_height=120,
               subtitle="Life expectancy above and below the average of all years")
plot.points(x="fertility", y="life_expect", color="gap", size=5, tooltip=["country"])
plot.colormap(scale="diverging", midpoint=0)
plot

A gradient is hard to read a value back from. A binned scale gives about bins= steps of round width (10–20, 20–30, ...), a colour each, and its legend lists them; a quantile scale gives exactly bins= steps with as many values in each, for skewed columns such as population. format(color=) writes the ranges:

plot = Trellis(gap, wrap="year", cols=4, panel_height=120)
plot.points(x="fertility", y="life_expect", color="pop", size=5, tooltip=["country"])
plot.colormap("cividis", scale="quantile", bins=4).format(color=".2s")
plot

With a database (load="pages"), only a binned scale works: a quantile one needs every row's value.

Order categories

Categories (panels, bands on an axis, colours) are in alphabetical order, except a pandas Categorical or a Polars Enum, which keep their own. order() sets it:

plot.order("month", ["Jan", "Feb", "Mar"])              # these first, the rest after
plot.order("site", by="median", of="yield")             # by a summary of another column
plot.order("site", by="median", of="yield", descending=True)

Months are text, so they too would be alphabetical (Apr, Aug, Dec, ...). Listing them puts them in calendar order, on the axis here:

from anytrellis import Trellis
from anytrellis.synthetic import sales

months = "Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec".split()
plot = Trellis(sales(), wrap="store", panel_height=150)
plot.line(x="month", y="units", color="product").order("month", months)
plot

by= takes "median", "mean", "min", "max", "sum" or "count". Ordering panels by what they show, rather than by name, is what makes many patterns visible: see the barley example in Coming from Altair or lattice.

The legend

The legend lists each colour column's categories, or its range. Clicking an entry selects that colour's marks; Shift+click adds or removes more (see Select data).

In a wrap whose last row is not full, the legend goes in the empty cells when it fits; legend() puts it elsewhere or renames it (see Layout).

Light and dark

The plot follows the notebook's theme: JupyterLab's, VS Code's or marimo's light and dark themes, and these pages' (try the toggle at the top). Marks keep their colours; the background, grid and text change.