Themes¶

Built-in themes and Theme / set_default_theme / theme_context.

Ferrum — a statistical visualization library with a Rust core.

Theme ¶

Immutable theme value class for chart styling.

Pass to Chart.theme(t) per-chart or activate process-wide via set_default_theme(t). Per-chart .theme() always wins at render time.

Cascade behavior: Chart.theme(t) replaces the entire active theme with t — it does not merge individual keys. To override a subset of keys on top of an existing theme, use Theme.update()::

base = fm.themes.paper_ink
custom = base.update(grid=False, padding=20)
chart.theme(custom)

All keys listed in ferrum-spec.md §3.13 are plumbed end-to-end to the Rust renderer. Unknown keys raise ValueError at construction.

Parameters:

Name	Type	Description	Default
`background`	`str`	Chart background color as a CSS hex string (e.g. `"#ffffff"`). `background_color` accepted as an alias.	required
`mark_color`	`str`	Default mark fill/stroke color for marks that have no explicit color encoding.	required
`font_family`	`optional`	Default body-text styling. `font_size` sets the label/body font size (the Rust binding's `label_font_size`), the same way `background` is the public alias for `background_color`.	required
`font_weight`	`optional`	Default body-text styling. `font_size` sets the label/body font size (the Rust binding's `label_font_size`), the same way `background` is the public alias for `background_color`.	required
`font_color`	`optional`	Default body-text styling. `font_size` sets the label/body font size (the Rust binding's `label_font_size`), the same way `background` is the public alias for `background_color`.	required
`font_size`	`optional`	Default body-text styling. `font_size` sets the label/body font size (the Rust binding's `label_font_size`), the same way `background` is the public alias for `background_color`.	required
`title_font_family`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset `title_` / `label_` keys fall back to their body-text counterpart (see the "Fallbacks" list below).	required
`title_font_size`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset `title_` / `label_` keys fall back to their body-text counterpart (see the "Fallbacks" list below).	required
`title_font_weight`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset `title_` / `label_` keys fall back to their body-text counterpart (see the "Fallbacks" list below).	required
`title_color`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset `title_` / `label_` keys fall back to their body-text counterpart (see the "Fallbacks" list below).	required
`title_anchor`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset `title_` / `label_` keys fall back to their body-text counterpart (see the "Fallbacks" list below).	required
`title_offset`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset `title_` / `label_` keys fall back to their body-text counterpart (see the "Fallbacks" list below).	required
`label_font_family`	`optional`	Tick label styling (see the "Fallbacks" list below).	required
`label_color`	`optional`	Tick label styling (see the "Fallbacks" list below).	required
`grid`	`bool`	Whether to draw grid lines (default True).	required
`grid_color`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`grid_width`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`grid_dash`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`grid_opacity`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`axis_line`	`bool`	Whether to draw axis strokes (default True).	required
`axis_line_color`	`optional`	Axis and tick styling.	required
`axis_line_width`	`optional`	Axis and tick styling.	required
`tick_color`	`optional`	Axis and tick styling.	required
`tick_size`	`optional`	Axis and tick styling.	required
`tick_width`	`optional`	Axis and tick styling.	required
`point_size`	`optional`	Mark styling.	required
`point_opacity`	`optional`	Mark styling.	required
`line_stroke_width`	`optional`	Mark styling.	required
`bar_corner_radius`	`optional`	Mark styling.	required
`area_opacity`	`optional`	Mark styling.	required
`opacity`	`optional`	Mark styling.	required
`color_scheme`	`str`	Named categorical palette: one of `paper_ink` (default), `slate_citrus`, `arctic_signal`, `okabe_ito`, `tableau10`, `set1`, `set2`, `paired`, `pastel`, `dark2`. Sequential names (`viridis`, `plasma`, `magma`, `inferno`, `cividis`, `blues`, `reds`, `greens`, `oranges`, `purples`, `cool_blue`, `warm_ochre`, `night_blue`, `electric_lime`, `signal_blue`, `ember_orange`) and diverging names (`rdbu`, `blue_to_red`, `cyan_to_amber`, `blue_to_violet`) also accepted.	required
`sequential_scheme`	`str`	Default sequential color ramp used by heatmaps, density plots, and other continuous-color charts when no explicit `cmap` is given. Must be one of the recognized sequential/diverging names. Defaults to `"cool_blue"` (Paper Ink).	required
`diverging_scheme`	`str`	Default diverging color ramp used by correlation matrices and other diverging-color charts when no explicit `cmap` is given. Must be one of the recognized sequential/diverging names. Defaults to `"blue_to_red"` (Paper Ink).	required
`legend_orient`	`optional`	Legend layout.	required
`legend_direction`	`optional`	Legend layout.	required
`legend_title_font_size`	`optional`	Legend layout.	required
`padding`	`optional`	Spacing in pixels.	required
`axis_title_padding`	`optional`	Spacing in pixels.	required
`column_padding`	`optional`	Spacing in pixels.	required
`row_padding`	`optional`	Spacing in pixels.	required
`reference_line_color`	`optional`	Color and dash pattern for reference / annotation guide lines.	required
`reference_line_dash`	`optional`	Color and dash pattern for reference / annotation guide lines.	required
`strip_background_color`	`optional`	Facet strip-title background color.	required
`strip_text_size`	`float`	Font size for facet strip titles (default 12).	required
`strip_padding`	`float`	Vertical padding around facet strip titles (default 6).	required
`cull_threshold`	`int`	Minimum number of pixels between adjacent axis tick labels before culling kicks in. Labels are dropped until the remaining labels are at least this many pixels apart. Default 8 (set in Rust). Set to `0` to disable culling entirely.	required

Fallbacks

When a title_* / label_* key is unset, it falls back to its body-text counterpart at render time. The pair list below is generated from Theme._FALLBACKS (the single source of truth):

%(fallbacks)s

Raises:

Type	Description
`ValueError`	If any keyword argument is not in the supported key list (see `Theme._KNOWN_KEYS`).

Examples:

>>> import ferrum as fm
>>> t = fm.Theme(background="#f9f9f9", grid=False, padding=16)
>>> t2 = t.update(mark_color="#e74c3c")
>>> t2
Theme(background='#f9f9f9', grid=False, mark_color='#e74c3c', padding=16)

update ¶

update(**kwargs: Any) -> 'Theme'

Return a new Theme with the given properties overridden.

Passing None for a key removes that property from the derived theme. The source theme is unchanged (immutable).

Parameters:

Name	Type	Description	Default
`**kwargs`	`any`	Property overrides. Pass `None` to clear a property.	`{}`

Returns:

Type	Description
`Theme`	A new `Theme` with the merged properties.

Examples:

>>> import ferrum as fm
>>> base = fm.Theme(grid=False, padding=12)
>>> with_bg = base.update(background_color="#222")

to_spec_dict ¶

to_spec_dict() -> dict

Return a dict suitable for ferrum._core.render_svg(theme=...).

Resolves spec-defined fallbacks (e.g. title_color falls back to font_color if unset) and normalises the public Python alias background to the Rust binding's canonical background_color key. CSS shorthand hex colors (#rgb / #rgba) are expanded by the Rust color parser (from_hex_str); Python forwards color strings unchanged. Rust sees a fully-resolved dict; no Option fallback chains in the binding.

get_default_theme ¶

get_default_theme() -> Theme

Return the current process-default theme.

Returns:

Type	Description
`Theme`	The currently active process-default theme. Starts as `ferrum.themes.default` (Rust renderer defaults); changes after each `set_default_theme()` call.

Examples:

>>> import ferrum as fm
>>> fm.get_default_theme()
Theme()

set_default_theme ¶

set_default_theme(theme: Theme) -> AbstractContextManager

Set the process-default theme for all subsequent charts.

The returned object is a context manager. Use it with with to scope the default to a block (previous default is restored on __exit__). Fire-and-forget usage (without with) is also supported.

Per-chart Chart.theme(t) always overrides this process default.

Parameters:

Name	Type	Description	Default
`theme`	`Theme`	Theme to install as the process default.	required

Returns:

Type	Description
`AbstractContextManager`	Context manager that restores the prior default on `__exit__`.

Raises:

Type	Description
`TypeError`	If `theme` is not a `Theme` instance.

Examples:

Fire-and-forget:

>>> import ferrum as fm
>>> fm.set_default_theme(fm.themes.dark)

Scoped to a block:

>>> with fm.set_default_theme(fm.themes.dark):
...     chart = fm.Chart(df).mark_point().encode(x="hp", y="mpg")

theme_context ¶

theme_context(theme: Theme) -> AbstractContextManager

Context-manager-spelling alias for :func:set_default_theme. See it for full semantics.