Configure¶

Chart-level configuration dataclasses — Configure, AxisConfig, ColorConfig, GridConfig, LegendConfig, PaddingConfig, TitleConfig — plus format-preset resolution (resolve_format) and the Chart.override error (FerrumOverrideError).

Ferrum — a statistical visualization library with a Rust core.

AxisConfig `dataclass` ¶

Chart-level axis configuration applied uniformly to all axes (or a specific one).

Parameters:

Name	Type	Description	Default
`x`	`bool`	Deprecated and has no effect. Use `Chart.axis(x=False)` / `Chart.axis(y=False)` to show or hide an axis.	`True`
`y`	`bool`	Deprecated and has no effect. Use `Chart.axis(x=False)` / `Chart.axis(y=False)` to show or hide an axis.	`True`
`label_angle`	`float`	Tick label rotation angle in degrees.	`None`
`label_font_size`	`float`	Tick label font size.	`None`
`label_color`	`str`	Tick label color.	`None`
`label_format`	`str`	Named format preset (see `ferrum.format_presets`). Must be a recognized preset key; raises `ValueError` at construction otherwise. For a raw d3-format/strftime string, use `label_format_raw` instead. Mutually exclusive with `label_format_raw`.	`None`
`label_format_raw`	`str`	Raw d3-format or strftime string passed directly to the renderer. Mutually exclusive with `label_format`.	`None`
`label_overlap`	`str`	Label overlap strategy: `"greedy"` (the graduated collision cascade, the default), `"parity"` (stride-2 decimation), `"rotate"` (force the rotate stage), or `"true"`/`"false"` (show every label / the `"greedy"` alias). An unrecognized token raises `ValueError` at construction naming the accepted set.	`None`
`tick_count`	`int`	Suggested number of ticks.	`None`
`tick_size`	`float`	Tick mark length in pixels.	`None`
`tick_values`	`list`	Explicit tick values.	`None`
`title_font_size`	`float`	Axis title font size.	`None`
`title_color`	`str`	Axis title color.	`None`
`title_padding`	`float`	Padding between the axis title and tick labels.	`None`
`label_padding`	`float`	Pixel gap between the tick mark endpoint and the label text baseline. Defaults to 2.0 when not set.	`None`
`domain`	`bool`	Show the axis domain line.	`None`
`domain_color`	`str`	Domain line color.	`None`
`domain_width`	`float`	Domain line width.	`None`
`grid`	`bool`	Show grid lines.	`None`
`grid_color`	`str`	Grid line color.	`None`
`grid_dash`	`list[float]`	Grid line dash pattern.	`None`
`grid_width`	`float`	Grid line width.	`None`
`domain_min`	`float`	Minimum value of the scale domain.	`None`
`domain_max`	`float`	Maximum value of the scale domain.	`None`
`nice`	`bool`	Round the scale domain to nice round values.	`None`
`zero`	`bool`	Include zero in the scale domain.	`None`
`grid_opacity`	`float`	Grid line opacity (0--1).	`None`
`orient`	`str`	Axis side: `"top"`/`"bottom"` (x) or `"left"`/`"right"` (y). Because chart-level `axis` applies to both axes, a single value is valid for only one of them; set `orient` via `axis_x` / `axis_y` (or per-channel `fm.Axis(orient=...)`) instead of the general `axis`.	`None`
`translate`	`float`	Pixel translation of the axis group perpendicular to its line.	`None`
`min_band`	`float`	Lower bound for the reserved axis margin band, in pixels.	`None`
`max_band`	`float`	Upper bound for the reserved axis margin band, in pixels. .. deprecated:: 0.17.0 `min_extent` and `max_extent` are accepted as aliases for `min_band` and `max_band` respectively, but are deprecated and will be removed in a future release.	`None`
`tick_extra`	`bool`	Append an extra tick at each domain boundary.	`None`
`tick_min_step`	`float`	Minimum step between ticks in data space.	`None`
`title_orient`	`str`	Side/orientation of the axis title.	`None`
`zindex`	`int`	Coarse draw order of the axis relative to marks.	`None`
`labels`	`bool`	Show or hide the tick labels. A per-channel `fm.Axis(labels=...)` wins over this.	`None`
`ticks`	`bool`	Show or hide the tick marks. Same precedence as `labels`.	`None`
`title`	`str or None`	Axis title text, following the same three-way contract as the per-channel :class:`~ferrum.axis.Axis` surface (one policy, one implementation — see :mod:`ferrum._title_sentinel`): omit it to keep the field-name default, pass `None` to suppress the title, or pass a string to use it verbatim. `""` also suppresses. A per-channel `X(title=...)` / `fm.Axis(title=...)` wins over this, including when the per-channel value is the suppression — a chart-level title never resurrects a title the channel deliberately removed.	`_UNSET`
`offset`	`float`	Shift the axis away from the plot edge by N pixels.	`None`
`label_flush`	`bool`	Align the first and last tick labels flush with the axis ends instead of letting them overhang the plot bounds.	`None`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

label_format preset names are resolved to their d3-format/strftime strings via :func:ferrum.format_presets.resolve_format_field before serialization (NF-B1) so the Rust side receives a ready-to-use format spec; __init__ already rejected any unrecognized name at construction, so resolution here always succeeds. The resolved format_type is threaded onto the wire as label_format_type. The deprecated, no-op x/y flags are never emitted — the wire schema does not accept them.

ColorConfig `dataclass` ¶

Chart-level color scale configuration.

Parameters:

Name	Type	Description	Default
`scheme`	`str`	Named color scheme for categorical encodings.	`None`
`sequential_scheme`	`str`	Named scheme for sequential (single-hue) encodings.	`None`
`diverging_scheme`	`str`	Named scheme for diverging encodings.	`None`
`domain`	`list`	Explicit scale domain values.	`None`
`range`	`list[str]`	Explicit list of color strings for the range.	`None`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

Configure `dataclass` ¶

Container for chart-level configuration overrides.

Each field maps to a specific configuration domain. Unset fields (None) mean "use the chart/theme default" — only fields that are explicitly set are forwarded to the renderer.

Parameters:

Name	Type	Description	Default
`axis`	`AxisConfig`	Applies to all axes.	`None`
`axis_x`	`AxisConfig`	Applies only to the x axis (overrides `axis` for x).	`None`
`axis_y`	`AxisConfig`	Applies only to the y axis (overrides `axis` for y).	`None`
`axis_y2`	`AxisConfig`	Applies only to the secondary y axis.	`None`
`legend`	`LegendConfig`	Legend appearance.	`None`
`title`	`TitleConfig`	Chart title appearance.	`None`
`grid`	`GridConfig`	Grid line appearance.	`None`
`padding`	`PaddingConfig`	Plot-area padding.	`None`
`color`	`ColorConfig`	Default color scale settings.	`None`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None fields and recursing into sub-configs.

FerrumOverrideError ¶

Bases: Exception

Raised when a override path cannot be resolved.

Chart.override(**kwargs) is a flat snake_case escape hatch onto the chart's presentation spec. Because the Rust spec deserializers silently drop unknown fields, a misspelled or unsupported path would otherwise be a silent no-op. Override paths are therefore validated Python-side against a registry generated from the live schemas; any path that does not resolve (unknown prefix, or a known prefix with a leaf that is not a valid field of its target) raises this error at render time, naming the offending path and — when a close match exists — suggesting the nearest valid path.

Examples:

>>> import ferrum as fm
>>> chart.override(x_axis_lable_angle=-45).to_svg()
Traceback (most recent call last):
    ...
ferrum.exceptions.FerrumOverrideError: Unknown override path
'x_axis_lable_angle'. Did you mean: 'x_axis_label_angle'?

GridAxisConfig `dataclass` ¶

One axis's own grid settings, for configure_grid(x=...) / y=.

The richer of the two spellings a per-axis grid slot accepts. A bare bool (configure_grid(x=False)) is the enable-only shorthand and stays supported unchanged; pass this instead when the axis also needs its own gridline style::

chart.configure_grid(
    x=fm.GridAxisConfig(enabled=True, color="#eee", dash=[2, 2]),
    y=False,
)

Anything left None falls back to GridConfig's flat both-axes shorthand, and then to the theme.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	Draw gridlines for this axis.	`None`
`color`	`str`	Gridline color for this axis.	`None`
`width`	`float`	Gridline width in pixels for this axis.	`None`
`dash`	`list[float]`	Gridline dash pattern (on/off pixel lengths) for this axis.	`None`
`opacity`	`float`	Gridline opacity (0--1) for this axis.	`None`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

GridConfig `dataclass` ¶

Chart-level grid configuration.

Parameters:

Name	Type	Description	Default
`x`	`bool or GridAxisConfig`	Show x-axis grid lines. Pass a :class:`GridAxisConfig` to give the x axis its own gridline style as well as its own enable flag.	`None`
`y`	`bool or GridAxisConfig`	Show y-axis grid lines; same two spellings as `x`.	`None`
`color`	`str`	Grid line color for both axes; an axis's own `color` wins.	`None`
`width`	`float`	Grid line width.	`None`
`dash`	`list[float]`	Grid line dash pattern.	`None`
`opacity`	`float`	Grid line opacity.	`None`
`band_colors`	`list[str]`	Alternating band fill colors between grid lines.	`None`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

x/y serialize as a bare bool when given one (the historical wire spelling every existing caller emits) and as a nested object otherwise. __post_init__ has already normalized any mapping into a :class:GridAxisConfig, so exactly one nested type reaches here.

LegendConfig `dataclass` ¶

Chart-level legend configuration.

Parameters:

Name	Type	Description	Default
`orient`	`str`	Legend position: `"right"`, `"left"`, `"top"`, `"bottom"`, or `"none"`.	`None`
`direction`	`str`	Layout direction: `"vertical"` or `"horizontal"`.	`None`
`columns`	`int`	Number of columns for multi-column layout.	`None`
`title_font_size`	`float`	Legend title font size.	`None`
`label_font_size`	`float`	Legend label font size.	`None`
`label_color`	`str`	Legend label color.	`None`
`label_limit`	`float`	Maximum legend-label width in pixels; wider labels are truncated with an ellipsis.	`None`
`symbol_size`	`float`	Symbol size.	`None`
`symbol_stroke_width`	`float`	Stroke width of legend symbol swatches in pixels.	`None`
`symbol_type`	`str`	Symbol shape type.	`None`
`gradient_length`	`float`	Gradient legend length.	`None`
`gradient_thickness`	`float`	Gradient legend thickness in pixels.	`None`
`title_padding`	`float`	Padding between the legend title and its entries.	`None`
`row_padding`	`float`	Vertical entry spacing in pixels (vertical-direction legends).	`None`
`column_padding`	`float`	Horizontal entry spacing in pixels (horizontal-direction legends).	`None`
`clip_height`	`float`	Cap on the legend group height in pixels; overflow is hard-clipped.	`None`
`tick_min_step`	`float`	Minimum step between colorbar ticks in data units.	`None`
`offset`	`float`	Offset from the plot area.	`None`
`padding`	`float`	Internal padding.	`None`
`zindex`	`int`	Coarse draw order of the legend relative to marks.	`None`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

PaddingConfig `dataclass` ¶

Chart-level padding configuration.

Parameters:

Name	Type	Description	Default
`top`	`float`	Top padding in pixels.	`None`
`right`	`float`	Right padding in pixels.	`None`
`bottom`	`float`	Bottom padding in pixels.	`None`
`left`	`float`	Left padding in pixels.	`None`
`auto`	`bool`	Opt-in, per-side auto-expand (D10, spec §4.7): a side still at its own default here (`None`) is expanded, when `auto=True`, to keep a continuous axis's edge-tick label or axis title from clipping past the rendered viewport edge. A side you do set is never touched by `auto` — an explicit value always wins on its own side. Does not affect ordinal/nominal axis labels (which never overhang the plot edge) or annotations; a y-axis capped tight enough via `max_band` can still leave its own label or title outside the canvas on that axis.	`False`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

TitleConfig `dataclass` ¶

Chart-level title configuration.

Parameters:

Name	Type	Description	Default
`font_size`	`float`	Title font size.	`None`
`font_weight`	`str`	Title font weight (e.g. `"bold"`, `"600"`).	`None`
`anchor`	`str`	Horizontal anchor: `"start"`, `"middle"`, or `"end"`.	`None`
`color`	`str`	Title color.	`None`
`offset`	`float`	Pixel offset from the plot area.	`None`
`subtitle_font_size`	`float`	Subtitle font size.	`None`
`subtitle_color`	`str`	Subtitle color.	`None`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

resolve_format ¶

resolve_format(name: str) -> str

Resolve a named preset to its d3-format or strftime string.

Parameters:

Name	Type	Description	Default
`name`	`str`	A key from `ALL_PRESETS`.	required

Returns:

Type	Description
`str`	The corresponding format string.

Raises:

Type	Description
`ValueError`	If name is not a recognized preset key.

Examples:

>>> resolve_format("percent")
'.1%'
>>> resolve_format("date_iso")
'%Y-%m-%d'

Configure¶

AxisConfig dataclass ¶

to_dict ¶

ColorConfig dataclass ¶

to_dict ¶

Configure dataclass ¶

to_dict ¶

FerrumOverrideError ¶

GridAxisConfig dataclass ¶

to_dict ¶

GridConfig dataclass ¶

to_dict ¶

LegendConfig dataclass ¶

to_dict ¶

PaddingConfig dataclass ¶

to_dict ¶

TitleConfig dataclass ¶

to_dict ¶

resolve_format ¶

AxisConfig `dataclass` ¶

ColorConfig `dataclass` ¶

Configure `dataclass` ¶

GridAxisConfig `dataclass` ¶

GridConfig `dataclass` ¶

LegendConfig `dataclass` ¶

PaddingConfig `dataclass` ¶

TitleConfig `dataclass` ¶