Annotations¶

annotate_* helpers, label classes, and annotation coordinates.

Ferrum — a statistical visualization library with a Rust core.

APLabel `dataclass` ¶

Auto-placed Average Precision annotation for PR charts.

Sibling of :class:AUCLabel for precision-recall curves. x is treated as recall and y as precision. Computes step-function area under the curve per series.

Parameters:

Name	Type	Description	Default
`position`	`('end', 'corner')`	Where to place the label. `"end"` puts it at the rightmost point of each series curve; `"corner"` anchors it near the top-right of the plot area.	`"end"`
`format`	`str`	Python format spec applied to the AP value.	`".3f"`
`prefix`	`str`	Text prepended to the formatted metric value.	`"AP = "`

Examples:

>>> import ferrum as fm
>>> chart = fm.pr_chart(model, X_test, y_test)
>>> annotated = chart + fm.APLabel()

AUCLabel `dataclass` ¶

Auto-placed AUC annotation for ROC charts.

chart + AUCLabel() reads the surrounding chart's line data (x = FPR, y = TPR), computes trapezoidal AUC per series (grouped by color when present), and emits one text annotation per series at the line endpoint.

Parameters:

Name	Type	Description	Default
`position`	`('end', 'corner')`	Where to place the label. `"end"` puts it at the rightmost point of each series curve; `"corner"` anchors it near the top-right of the plot area.	`"end"`
`format`	`str`	Python format spec applied to the AUC value (e.g. `".2f"` for two decimal places).	`".3f"`
`prefix`	`str`	Text prepended to the formatted metric value.	`"AUC = "`

Examples:

>>> import ferrum as fm
>>> chart = fm.roc_chart(model, X_test, y_test)
>>> annotated = chart + fm.AUCLabel()

Annotate `dataclass` ¶

A collection of annotation primitives to attach to a chart.

Parameters:

Name	Type	Description	Default
`items`	`annotation primitive or list of annotation primitives`	A single primitive or a list of primitives created by the factory functions in :mod:`ferrum.annotation`.	required

Examples:

>>> import ferrum.annotation as ann
>>> from ferrum.annotation import Annotate
>>> annotations = Annotate([
...     ann.text(1.0, 2.0, "peak"),
...     ann.span("x", 0, 1, fill="#eee"),
... ])

to_dict_list ¶

to_dict_list() -> list[dict[str, Any]]

Serialize all items to a list of dicts for renderer transport.

BrierLabel `dataclass` ¶

Auto-placed Brier-score annotation for calibration charts.

x is treated as predicted probability and y as observed rate per bin. Multi-series charts emit one Brier score per series. Lower scores indicate better calibration.

Parameters:

Name	Type	Description	Default
`position`	`('end', 'corner')`	Where to place the label. `"corner"` anchors it near the top-right of the plot area; `"end"` puts it at the last bin.	`"end"`
`format`	`str`	Python format spec applied to the Brier score value.	`".3f"`
`prefix`	`str`	Text prepended to the formatted metric value.	`"Brier = "`

Examples:

>>> import ferrum as fm
>>> chart = fm.calibration_chart(model, X_test, y_test)
>>> annotated = chart + fm.BrierLabel()

NormCoord `dataclass` ¶

A normalized coordinate in [0, 1] relative to the plot area.

Parameters:

Name	Type	Description	Default
`value`	`float`	0.0 is the left/bottom edge, 1.0 is the right/top edge.	required

OutlierLabel `dataclass` ¶

Auto-label high-leverage or high-residual points on a scatter chart.

chart + OutlierLabel() scans the chart's y column for values whose z-score exceeds threshold, then overlays text labels at those points. The label text is taken from label_field when supplied, otherwise from the field column, otherwise from the y value.

Parameters:

Name	Type	Description	Default
`threshold`	`float`	Z-score threshold above which a point is considered an outlier and labelled.	`3.0`
`field`	`str`	Column to compute z-scores from. Defaults to the chart's `y` encoding field.	`None`
`label_field`	`str`	Column whose value is used as the text label. Defaults to `field` when omitted.	`None`
`max_labels`	`int`	Maximum number of labels to emit. Points are ranked by absolute z-score and only the top `max_labels` are labelled.	`10`

Examples:

>>> import ferrum as fm
>>> chart = fm.residuals_chart(model, X_test, y_test)
>>> annotated = chart + fm.OutlierLabel(threshold=2.5, max_labels=5)

PixelCoord `dataclass` ¶

An absolute pixel coordinate relative to the plot origin.

Parameters:

Name	Type	Description	Default
`value`	`float`	Pixel offset from the plot's top-left corner.	required

annotate_abline ¶

annotate_abline(slope: float, intercept: float, *, stroke: str = 'black', stroke_width: float = 1.0, stroke_dash: 'list[float] | None' = None, opacity: float = 1.0) -> Chart

Draw the line y = slope * x + intercept across the full x extent.

Returns a two-point mark_line chart whose x range spans [-1e6, 1e6]; the Rust renderer clips the line to the plot area automatically. The chart is suitable for layering with +::

scatter + fm.annotate_abline(slope=1.0, intercept=0.0, stroke="gray")

Parameters:

Name	Type	Description	Default
`slope`	`float`	Line slope (rise over run).	required
`intercept`	`float`	Y-intercept (value of y when x = 0).	required
`stroke`	`str`	Line color as a CSS color string.	`"black"`
`stroke_width`	`float`	Line width in pixels.	`1.0`
`stroke_dash`	`list of float`	SVG dash array, e.g. `[4, 4]` for evenly dashed.	`None`
`opacity`	`float`	Line opacity in `[0, 1]`.	`1.0`

Returns:

Type	Description
`Chart`	Two-point line chart suitable for `+` layering.

Examples:

>>> import ferrum as fm
>>> import polars as pl
>>> df = pl.DataFrame({"x": [0.0, 1.0], "y": [0.1, 0.9]})
>>> scatter = fm.Chart(df).mark_point().encode(x="x:Q", y="y:Q")
>>> identity = fm.annotate_abline(slope=1.0, intercept=0.0, stroke="gray")
>>> chart = scatter + identity

annotate_arrow ¶

annotate_arrow(x1: _AnnotationCoord, y1: _AnnotationCoord, x2: _AnnotationCoord, y2: _AnnotationCoord, *, label: Optional[str] = None, label_side: str = 'start', stroke: Optional[str] = None) -> Chart

Draw an arrow from (x1, y1) to (x2, y2) with an optional text label.

Composes a mark_segment (the arrow shaft) with an optional annotate_text placed at the label_side endpoint.

Parameters:

Name	Type	Description	Default
`x1`	`float, datetime.date, datetime.datetime, or str`	Horizontal data coordinate of the arrow start.	required
`y1`	`float, datetime.date, datetime.datetime, or str`	Vertical data coordinate of the arrow start.	required
`x2`	`float, datetime.date, datetime.datetime, or str`	Horizontal data coordinate of the arrow end (tip).	required
`y2`	`float, datetime.date, datetime.datetime, or str`	Vertical data coordinate of the arrow end (tip).	required
`label`	`str`	Text to display alongside the arrow. When omitted, no text is rendered.	`None`
`label_side`	`('start', 'end')`	Which end of the arrow to place the label. `"start"` anchors the text at `(x1, y1)`; `"end"` places it at `(x2, y2)`.	`"start"`
`stroke`	`str`	Hex colour string for the arrow line (e.g. `"#ff0000"`). Inherits the theme's foreground colour when omitted.	`None`

Returns:

Type	Description
`Chart`	Layered chart containing the arrow segment and, when label is provided, the annotation text.

Examples:

Simple unlabelled arrow:

>>> import ferrum as fm
>>> fm.annotate_arrow(0.1, 0.5, 0.8, 0.9)

Arrow with a label at the tip:

>>> fm.annotate_arrow(0.1, 0.5, 0.8, 0.9, label="threshold", label_side="end")

annotate_hline ¶

annotate_hline(y: _AnnotationCoord, *, label: Optional[str] = None, stroke: Optional[str] = None, stroke_dash=None) -> Chart

Horizontal reference line at a fixed y position.

Returns a single-mark Chart suitable for | / & concatenation composition; for true overlay/layer, use + with a chart that shares the same DataFrame.

Parameters:

Name	Type	Description	Default
`y`	`float, datetime.date, datetime.datetime, or str`	Y position of the line in data coordinates. Temporal values (`date`, `datetime`, ISO-8601 strings) are converted to epoch-milliseconds (UTC) to align with ferrum's temporal axis scale.	required
`label`	`str`	Reserved for future use (no-op today).	`None`
`stroke`	`str`	Line color as a CSS color string. Defaults to the mark default when omitted.	`None`
`stroke_dash`	`list of float`	SVG dash array, e.g. `[4, 4]` for evenly dashed.	`None`

Returns:

Type	Description
`Chart`	Annotation chart suitable for `\|` / `&` composition.

Examples:

>>> import ferrum as fm
>>> ref = fm.annotate_hline(y=0.0, stroke="red", stroke_dash=[4, 4])
>>> chart = fm.Chart(df).encode(x="t", y="r").mark_line() & ref

annotate_rect ¶

annotate_rect(x1: _AnnotationCoord, x2: _AnnotationCoord, y1: _AnnotationCoord, y2: _AnnotationCoord, *, fill: Optional[str] = None, opacity: float = 0.1, label: Optional[str] = None) -> Chart

Shaded rectangle region spanning (x1, y1) to (x2, y2).

Returns a mark_rect annotation chart for | / & concatenation composition; for true overlay/layer, use + with a chart that shares the same DataFrame.

Parameters:

Name	Type	Description	Default
`x1`	`float, datetime.date, datetime.datetime, or str`	Left x boundary in data coordinates.	required
`x2`	`float, datetime.date, datetime.datetime, or str`	Right x boundary in data coordinates.	required
`y1`	`float, datetime.date, datetime.datetime, or str`	Bottom y boundary in data coordinates.	required
`y2`	`float, datetime.date, datetime.datetime, or str`	Top y boundary in data coordinates.	required
`fill`	`str`	Fill color as a CSS color string.	`None`
`opacity`	`float`	Fill opacity in `[0, 1]`.	`0.1`
`label`	`str`	Reserved for future use (no-op today).	`None`

Returns:

Type	Description
`Chart`	Annotation chart suitable for `\|` / `&` composition.

Examples:

>>> import ferrum as fm
>>> shade = fm.annotate_rect(x1=2018, x2=2020, y1=0, y2=100,
...                          fill="#ffcc00", opacity=0.2)
>>> chart = fm.Chart(df).encode(x="year", y="val").mark_line() & shade

annotate_text ¶

annotate_text(x: _AnnotationCoord, y: _AnnotationCoord, text: str, *, dx: float = 0, dy: float = 0, anchor: Optional[str] = None, align: Optional[str] = None, baseline: str = 'middle', font_size: Optional[float] = None, color: Optional[str] = None, angle: Optional[float] = None) -> Chart

Free-floating text annotation at a fixed (x, y) position.

Returns a mark_text chart for | / & concatenation composition; for true overlay/layer, use + with a chart that shares the same DataFrame.

Parameters:

Name	Type	Description	Default
`x`	`float, datetime.date, datetime.datetime, or str`	X position in data coordinates. Temporal values are converted to epoch-milliseconds (UTC).	required
`y`	`float, datetime.date, datetime.datetime, or str`	Y position in data coordinates. Temporal values are converted to epoch-milliseconds (UTC).	required
`text`	`str`	Text string to display.	required
`dx`	`float`	Horizontal pixel offset from `(x, y)`.	`0`
`dy`	`float`	Vertical pixel offset from `(x, y)`.	`0`
`anchor`	`str`	Horizontal text anchor in the SVG vocabulary (matching :func:`ferrum.annotation.text`): `"start"`, `"middle"`, or `"end"`. This is the canonical keyword. When neither `anchor` nor `align` is supplied the anchor defaults to `"middle"` (centered).	`None`
`align`	`str`	Deprecated alias for `anchor` in the `"left"`/`"center"`/ `"right"` vocabulary. Mapped to `anchor` via `{left: start, center: middle, right: end}`. Supplying both `anchor` and `align` raises `ValueError`.	`None`
`baseline`	`str`	Vertical text baseline: `"top"`, `"middle"`, or `"bottom"`.	`"middle"`
`font_size`	`float`	Font size in points.	`None`
`color`	`str`	Text fill color as a CSS color string.	`None`
`angle`	`float`	Rotation angle in degrees (clockwise).	`None`

Returns:

Type	Description
`Chart`	Annotation chart suitable for `\|` / `&` composition.

Examples:

>>> import ferrum as fm
>>> label = fm.annotate_text(x=2020, y=95, text="peak", dy=-8,
...                          color="#333", font_size=11)
>>> chart = fm.Chart(df).encode(x="year", y="val").mark_line() & label

annotate_vline ¶

annotate_vline(x: _AnnotationCoord, *, label: Optional[str] = None, stroke: Optional[str] = None, stroke_dash=None) -> Chart

Vertical reference line at a fixed x position.

Returns a single-mark Chart suitable for | / & concatenation composition; for true overlay/layer, use + with a chart that shares the same DataFrame.

Parameters:

Name	Type	Description	Default
`x`	`float, datetime.date, datetime.datetime, or str`	X position of the line in data coordinates. Temporal values (`date`, `datetime`, ISO-8601 strings) are converted to epoch-milliseconds (UTC) to align with ferrum's temporal axis scale.	required
`label`	`str`	Reserved for future use (no-op today).	`None`
`stroke`	`str`	Line color as a CSS color string.	`None`
`stroke_dash`	`list of float`	SVG dash array, e.g. `[4, 4]`.	`None`

Returns:

Type	Description
`Chart`	Annotation chart suitable for `\|` / `&` composition.

Examples:

>>> import ferrum as fm
>>> ref = fm.annotate_vline(x=2020, stroke="#888")
>>> chart = fm.Chart(df).encode(x="year", y="val").mark_line() & ref

norm ¶

norm(value: float) -> NormCoord

Construct a normalized [0, 1] coordinate.

Parameters:

Name	Type	Description	Default
`value`	`float`	Normalized fraction (0.0–1.0).	required

Returns:

Type	Description
`NormCoord`

Examples:

>>> norm(0.5)
NormCoord(value=0.5)

px ¶

px(value: float) -> PixelCoord

Construct a pixel-space coordinate.

Parameters:

Name	Type	Description	Default
`value`	`float`	Pixel offset.	required

Returns:

Type	Description
`PixelCoord`

Examples:

>>> px(50)
PixelCoord(value=50)

Annotations¶

APLabel dataclass ¶

AUCLabel dataclass ¶

Annotate dataclass ¶

to_dict_list ¶

BrierLabel dataclass ¶

NormCoord dataclass ¶

OutlierLabel dataclass ¶

PixelCoord dataclass ¶

annotate_abline ¶

annotate_arrow ¶

annotate_hline ¶

annotate_rect ¶

annotate_text ¶

annotate_vline ¶

norm ¶

px ¶

APLabel `dataclass` ¶

AUCLabel `dataclass` ¶

Annotate `dataclass` ¶

BrierLabel `dataclass` ¶

NormCoord `dataclass` ¶

OutlierLabel `dataclass` ¶

PixelCoord `dataclass` ¶