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`). 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: `"parity"`, `"greedy"`, `"rotate"`, or `"hide"`.	`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`

to_dict ¶

to_dict() -> dict[str, Any]

Serialize to dict, omitting None values.

label_format preset names are resolved to their d3-format strings before serialization so the Rust side receives a ready-to-use format spec.

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 :meth:ferrum.Chart.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'?

GridConfig `dataclass` ¶

Chart-level grid configuration.

Parameters:

Name	Type	Description	Default
`x`	`bool`	Show x-axis grid lines.	`None`
`y`	`bool`	Show y-axis grid lines.	`None`
`color`	`str`	Grid line color.	`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.

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`	When True and all four sides are None, let the renderer choose padding automatically.	`True`

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 ¶

GridConfig dataclass ¶

to_dict ¶

LegendConfig dataclass ¶

to_dict ¶

PaddingConfig dataclass ¶

to_dict ¶

TitleConfig dataclass ¶

to_dict ¶

resolve_format ¶

AxisConfig `dataclass` ¶

ColorConfig `dataclass` ¶

Configure `dataclass` ¶

GridConfig `dataclass` ¶

LegendConfig `dataclass` ¶

PaddingConfig `dataclass` ¶

TitleConfig `dataclass` ¶