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¶

Visual comparison¶

All twelve built-in themes applied to the same scatter-with-smooth chart:

Applying a theme¶

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)
)
chart

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_spec_dict()["background_color"] == "#f9f9f9"
assert darker.to_spec_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¶

Major and minor gridlines with fm.Grid¶

Passing a bool (grid=True/False) toggles a single level of gridlines. For two levels — major lines at the labelled ticks and lighter minor lines between them — pass a Grid value instead:

import ferrum as fm

theme = fm.Theme(grid=fm.Grid(major=True, minor=True, minor_color="#eeeeee"))

Grid carries per-level styling: major_color/minor_color, major_width/minor_width, major_dash/minor_dash, and major_opacity/minor_opacity. The bare color, width, dash, and opacity arguments are a shorthand that sets both levels; an explicit major_*/minor_* overrides that level. So fm.Grid(color="#f5f5f5") styles both major and minor the same, while fm.Grid(color="#eeeeee", minor_color="#f8f8f8") keeps major at #eeeeee and lightens only the minors.

Notes:

• Minor gridlines render on continuous axes only (linear, log, time, pow, sqrt, symlog). Categorical and discretizing axes have no continuum to subdivide, so minor=True is a documented no-op there — no error, no extra lines.
• Log axes place minors at the standard 2–9 intra-decade multiples (crowding toward each decade top), not at uniform subdivisions.
• Gridlines coincide with the data. On a continuous axis, a major gridline at value v lands exactly where a data mark at v renders; minors subdivide between them on the same grid.

Grid is theme-level. For per-chart gridline overrides see .configure_grid().

Axes¶

Marks¶

These are defaults. A constant mark-style kwarg on the mark itself wins — e.g. mark_density(opacity=0.6) overrides the theme's area_opacity. See Marks & Encodings.

Palettes¶

For programmatic palette access outside of themes, see ferrum.color.

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")
)
chart
fm.set_default_theme(fm.themes.default)

For process-level configuration defaults (width, height, renderer), see ferrum.config.

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")
    )
    publication_chart
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¶

All color keys in Theme — background, mark_color, font_color, grid_color, and others — accept either a CSS #rrggbb hex string or any of the 148 CSS named colors ("steelblue", "crimson", "coral", "goldenrod", etc.). Named colors are resolved at construction time, so Theme(mark_color="steelblue") is exactly equivalent to Theme(mark_color="#4682B4").

brand = fm.Theme(
    mark_color="steelblue",
    background="ivory",
    grid_color="lightgray",
)

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)
)
chart

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_spec_dict()["mark_color"] == "#0d47a1"
assert brand.to_spec_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.