ferrum.annotations¶

Lightweight overlays that don't participate in scale domain calculation.

Reference-line, rectangle, and text annotation helpers.

Metric-label classes (AUCLabel, APLabel, BrierLabel, OutlierLabel) and their private helpers live in ferrum._metric_labels; they are re-exported here for backward compatibility.

annotate_hline ¶

annotate_hline(y: float, *, 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`	Y position of the line in data coordinates.	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_vline ¶

annotate_vline(x: float, *, 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`	X position of the line in data coordinates.	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

annotate_rect ¶

annotate_rect(x1: float, x2: float, y1: float, y2: float, *, 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`	Left x boundary in data coordinates.	required
`x2`	`float`	Right x boundary in data coordinates.	required
`y1`	`float`	Bottom y boundary in data coordinates.	required
`y2`	`float`	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: float, y: float, text: str, *, dx: float = 0, dy: float = 0, align: str = 'center', 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`	X position in data coordinates.	required
`y`	`float`	Y position in data coordinates.	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`
`align`	`str`	Horizontal text alignment (SVG `text-anchor`): `"left"`, `"center"`, or `"right"`.	`"center"`
`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_arrow ¶

annotate_arrow(x1: float, y1: float, x2: float, y2: float, *, 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`	Horizontal data coordinate of the arrow start.	required
`y1`	`float`	Vertical data coordinate of the arrow start.	required
`x2`	`float`	Horizontal data coordinate of the arrow end (tip).	required
`y2`	`float`	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")