Skip to content

Structural

Structural view modifiers — BreakAxis, Inset, SecondaryY.

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"

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), PixelCoord, or 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.

chart + SecondaryY(...) desugars to an appended layer on chart: mark mark, y encoding on field (carrying axis/scale), x inherited from the base chart, color literal color, opacity opacity — flagged as an independent-y layer (GH #52). The base chart's own layer(s) are unchanged, so layered_chart + SecondaryY(...) keeps the base layers sharing the left axis while only the appended layer gets its own right axis; adding multiple SecondaryY instances stacks multiple right axes outward. The base chart must carry an x encoding for the secondary layer to inherit — adding SecondaryY to a chart with no x raises ValueError. field is read from the base chart's own table (the desugar performs no data merge), so a field that is not a column of the base data also raises ValueError at + time. mark must name a primitive mark (point, line, bar, area, rule, text, tick, rect) -- a composite mark name (e.g. "boxplot") would otherwise bypass the mark_*() desugar pipeline and reach the renderer as an unknown primitive, so it raises ValueError at + time; use LayerChart(chart, other_chart, resolve={"y": "independent"}) for a composite overlay on a secondary axis instead.

This re-bases the feature onto ferrum's per-layer independent-y subsystem: unlike the original overlay-only renderer, the secondary series now reserves its own right-side margin band (so the plot area narrows to make room for it, rather than the axis overdrawing the plot), gets a real axis (ticks, labels, per-encoding Axis(...) config), and is fully interactive (tooltips, zoom/pan, hit-testing) like any other layer.

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