Themes¶

A theme is a bundle of style decisions — background, typography, mark color, grid, axes, palettes, padding — that applies uniformly across a chart. Themes are values, not state: you construct a Theme and pass it where you want it. Nothing mutates global module state, and no chart is "secretly" themed by an import side-effect.

Three layers of theme control let you reach for the right scope: per-chart, process-default, and scoped via a context manager. Per-chart always wins.

Built-in themes¶

Ferrum ships twelve built-in themes accessible as attributes of [ferrum.themes][]. Three are original identities designed for Ferrum; the rest are established editorial and publication styles.

Ferrum originals¶

Established styles¶

Apply a theme to a chart:

import ferrum as fm
import polars as pl
from sklearn.datasets import load_iris

raw = load_iris()
iris = pl.DataFrame(raw.data, schema=["sepal_length", "sepal_width", "petal_length", "petal_width"]).with_columns(
    species=pl.Series([raw.target_names[t] for t in raw.target])
)
chart = (
    fm.Chart(iris)
    .mark_point()
    .encode(x="sepal_length", y="petal_length", color="species:N")
    .theme(fm.themes.slate_citrus)
)
assert chart.show_svg().startswith("<svg")

Switching themes is one method call away; the rest of the chart spec is untouched.

Theme as a value¶

Theme is immutable. Once constructed, it cannot be mutated. Methods like .update() return a new Theme rather than modifying the original:

import ferrum as fm

base = fm.Theme(background="#f9f9f9", grid=True, padding=16)
darker = base.update(background="#222222", mark_color="#e74c3c")
assert base != darker
assert base.to_theme_inputs_dict()["background_color"] == "#f9f9f9"
assert darker.to_theme_inputs_dict()["background_color"] == "#222222"

This immutability is structural: themes are values that compose, like encodings and marks. You can keep a "base theme" in a module and derive variants without worrying about side-effects.

Theme keys¶

Every key listed below is plumbed end-to-end from the Python Theme(...) constructor through the Rust renderer. Unknown keys raise ValueError at construction time — there are no silently ignored keys.

Canvas¶

Typography¶

Grid¶

Axes¶

Marks¶

Palettes¶

Layout and decoration¶

Available palettes¶

Categorical¶

Ten named categorical palettes, selectable via color_scheme:

Sequential¶

Twelve named sequential ramps, selectable via sequential_scheme:

Diverging¶

Four named diverging ramps, selectable via diverging_scheme:

Process-default themes¶

When you want the same theme to apply to every chart in a notebook or script, set it once with set_default_theme():

import ferrum as fm
import polars as pl
from sklearn.datasets import load_iris

raw = load_iris()
iris = pl.DataFrame(raw.data, schema=["sepal_length", "sepal_width", "petal_length", "petal_width"]).with_columns(
    species=pl.Series([raw.target_names[t] for t in raw.target])
)
fm.set_default_theme(fm.themes.dark)
chart = (
    fm.Chart(iris)
    .mark_point()
    .encode(x="sepal_length", y="petal_length", color="species:N")
)
assert chart.show_svg().startswith("<svg")
fm.set_default_theme(fm.themes.default)

set_default_theme() does not mutate a module-level config object. It writes to a per-thread contextvars.ContextVar, which means:

• The default is scoped to the current Python interpreter context.
• Concurrent tasks (asyncio, multiprocessing, threads using contextvars) do not share defaults.
• The previous default can be restored explicitly, or implicitly via the context manager (next section).

This is the single documented exception to Ferrum's "no global mutable state" rule, and the mechanism is deliberately scope-bounded.

Scoped themes via with¶

For code where the theme should change for one block and revert afterward, theme_context() is a context manager:

import ferrum as fm
import polars as pl
from sklearn.datasets import load_iris

raw = load_iris()
iris = pl.DataFrame(raw.data, schema=["sepal_length", "sepal_width", "petal_length", "petal_width"]).with_columns(
    species=pl.Series([raw.target_names[t] for t in raw.target])
)
with fm.theme_context(fm.themes.publication):
    publication_chart = (
        fm.Chart(iris)
        .mark_point()
        .encode(x="sepal_length", y="petal_length", color="species:N")
    )
    assert publication_chart.show_svg().startswith("<svg")
assert fm.get_default_theme() == fm.themes.default

The previous default is restored on __exit__. This is the right scope for a single section of a notebook, a single figure-rendering function, or a test fixture.

Precedence¶

When multiple theme sources are in play:

1. Per-chart .theme(t) always wins. If a chart calls .theme(dark), that chart renders with dark regardless of any process default.
2. Process default applies otherwise. A chart without an explicit .theme() picks up whatever set_default_theme() last set (or whatever theme_context() currently scopes).
3. Ferrum's built-in default (Paper Ink) is the bottom of the stack. If nothing else is set, every chart renders with the warm cream Paper Ink identity.

Think of .theme() as a chart-level override and set_default_theme() / theme_context() as ambient defaults.

Building a custom theme¶

A custom theme is a Theme(...) call with the keys you want:

import ferrum as fm
import polars as pl
from sklearn.datasets import load_iris

raw = load_iris()
iris = pl.DataFrame(raw.data, schema=["sepal_length", "sepal_width", "petal_length", "petal_width"]).with_columns(
    species=pl.Series([raw.target_names[t] for t in raw.target])
)
brand = fm.Theme(
    background="#ffffff",
    mark_color="#0d47a1",
    point_size=4.0,
    grid=False,
    padding=24,
    color_scheme="tableau10",
    sequential_scheme="viridis",
)
chart = (
    fm.Chart(iris)
    .mark_point()
    .encode(x="sepal_length", y="petal_length")
    .theme(brand)
)
assert chart.show_svg().startswith("<svg")

You can also derive from a built-in using .update():

import ferrum as fm

brand = fm.themes.paper_ink.update(
    mark_color="#0d47a1",
    grid=False,
    padding=24,
)
assert brand.to_theme_inputs_dict()["mark_color"] == "#0d47a1"
assert brand.to_theme_inputs_dict()["background_color"] == "#FAF7F2"

This produces a new Theme with Paper Ink's warm background and typography but your mark color and grid preferences. The original paper_ink theme is unchanged.

Where to go next¶

• Marks & encodings for what gets styled by a theme.
• Composition for how themes apply across compound views.
• Figure-level helpers for the convenience entry points (most accept a theme= keyword).
• The API Reference for the full Theme constructor signature.