Structural¶

Structural view modifiers — BreakAxis, Inset, SecondaryY, Grid.

Ferrum — a statistical visualization library with a Rust core.

BreakAxis `dataclass` ¶

An axis break that omits a region of the scale to skip outlier values.

Parameters:

Name	Type	Description	Default
`axis`	`str`	Which axis to break: `"x"` or `"y"`.	required
`gap`	`tuple or list`	A single `(start, end)` break region or a list of `(start, end)` tuples for multiple breaks.	required
`break_size`	`float`	Visual size of the break indicator in pixels.	`12`
`break_style`	`str`	Break indicator style: `"slash"`, `"zigzag"`, `"wave"`, or `"gap"`.	`"slash"`

Grid `dataclass` ¶

Theme-level grid configuration controlling major and minor gridlines.

Accepted by Theme(grid=...) / Theme.update(grid=fr.Grid(...)). Passing a bare bool remains valid (maps to the major enable flag).

Shorthand resolution. The bare color, width, dash, and opacity parameters are a fallback that sets both levels. An explicit major_* or minor_* value for that property overrides the bare value for that level only. Examples::

Grid(color="#f5f5f5")
# → major_grid_color="#f5f5f5", minor_grid_color="#f5f5f5"

Grid(color="#eee", minor_color="#f8f8f8")
# → major_grid_color="#eee", minor_grid_color="#f8f8f8"

The bare shorthand keys (color, width, dash, opacity) are never emitted to the Rust renderer; only resolved per-level keys appear in to_spec_dict() output.

Minor gridlines. minor=True renders minor gridlines on continuous axes (linear, log, time, pow, sqrt, symlog). On categorical or discretising axes (band, ordinal, quantile, threshold, bin-ordinal) there is no continuum to subdivide, so minor=True there is a semantic absence — no extra lines are drawn and no error is raised.

Parameters:

Name	Type	Description	Default
`major`	`bool`	Enable major gridlines.	`True`
`minor`	`bool`	Enable minor gridlines (continuous scales only).	`False`
`color`	`str`	Fallback color for both major and minor gridlines.	`None`
`width`	`float`	Fallback stroke width for both levels.	`None`
`dash`	`list of float`	Fallback dash pattern (SVG stroke-dasharray lengths) for both levels.	`None`
`opacity`	`float`	Fallback stroke opacity for both levels.	`None`
`major_color`	`str`	Major gridline color; overrides bare `color` for the major level.	`None`
`minor_color`	`str`	Minor gridline color; overrides bare `color` for the minor level.	`None`
`major_width`	`float`	Major gridline stroke width; overrides bare `width` for major.	`None`
`minor_width`	`float`	Minor gridline stroke width; overrides bare `width` for minor.	`None`
`major_dash`	`list of float`	Major gridline dash pattern; overrides bare `dash` for major.	`None`
`minor_dash`	`list of float`	Minor gridline dash pattern; overrides bare `dash` for minor.	`None`
`major_opacity`	`float`	Major gridline opacity; overrides bare `opacity` for major.	`None`
`minor_opacity`	`float`	Minor gridline opacity; overrides bare `opacity` for minor.	`None`

Examples:

>>> import ferrum as fm
>>> # Enable minor gridlines, both levels same colour
>>> g = fm.Grid(minor=True, color="#f5f5f5")
>>> g.to_spec_dict()
{'grid': True, 'minor': True, 'major_grid_color': '#f5f5f5', 'minor_grid_color': '#f5f5f5'}

>>> # Different colours per level
>>> g2 = fm.Grid(minor=True, color="#eeeeee", minor_color="#f8f8f8")
>>> g2.to_spec_dict()
{'grid': True, 'minor': True, 'major_grid_color': '#eeeeee', 'minor_grid_color': '#f8f8f8'}

>>> # Attach to a theme
>>> chart.theme(fm.themes.minimal.update(grid=fm.Grid(minor=True)))

to_spec_dict ¶

to_spec_dict() -> dict

Serialize to the dict shape the Rust binding expects.

Always emits grid (major enable) and minor (minor enable). Resolves shorthand → per-level: for each of color/width/dash/opacity, major level = major_X if not None else bare X; minor level = minor_X if not None else bare X. Only non-None resolved per-level styling keys are emitted. The bare shorthand keys are never present in the output.

Inset `dataclass` ¶

An inset chart embedded within a parent chart's plot area.

Parameters:

Name	Type	Description	Default
`chart`	`Chart`	The chart to embed as an inset.	required
`bounds`	`tuple`	`(left, top, right, bottom)` boundary coordinates for the inset within the parent plot area. Each coordinate may be a `float` (data-space), :class:`~ferrum.annotation.coords.PixelCoord`, or :class:`~ferrum.annotation.coords.NormCoord`.	required
`border`	`bool`	Draw a border around the inset.	`True`
`border_color`	`str`	Border color.	`"#999"`
`border_dash`	`list[float]`	Border dash pattern.	`None`
`background`	`str or None`	Inset background color; `None` for transparent.	`"#fff"`
`shadow`	`bool`	Apply a drop shadow to the inset.	`False`
`connect_to`	`tuple`	Data coordinates `(x, y)` of the source region in the parent chart that this inset zooms into. Draws a connector from the parent region to the inset when provided.	`None`
`connect_style`	`str`	Connector style: `"bracket"`, `"lines"`, or `"none"`.	`"lines"`

SecondaryY `dataclass` ¶

A secondary y-axis encoding overlaid on a chart.

Parameters:

Name	Type	Description	Default
`field`	`str`	Data field to encode on the secondary y axis.	required
`mark`	`str`	Mark type for the secondary series.	`"line"`
`axis`	`Axis`	Per-axis configuration for the secondary y axis.	`None`
`color`	`str`	Color for the secondary mark.	`None`
`opacity`	`float`	Opacity for the secondary mark.	`None`
`scale`	`Scale`	Scale configuration for the secondary y axis.	`None`

Structural¶

BreakAxis dataclass ¶

Grid dataclass ¶

to_spec_dict ¶

Inset dataclass ¶

SecondaryY dataclass ¶

BreakAxis `dataclass` ¶

Grid `dataclass` ¶

Inset `dataclass` ¶

SecondaryY `dataclass` ¶