tesorotools-python 0.0.44__tar.gz → 0.0.46__tar.gz

{tesorotools_python-0.0.44 → tesorotools_python-0.0.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.44
+Version: 0.0.46
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10
@@ -16,5 +16,8 @@ Provides-Extra: bde
 Requires-Dist: requests>=2.31; extra == 'bde'
 Provides-Extra: ecb
 Requires-Dist: requests>=2.31; extra == 'ecb'
+Provides-Extra: imf
+Requires-Dist: requests>=2.31; extra == 'imf'
+Requires-Dist: truststore>=0.10; extra == 'imf'
 Provides-Extra: lseg
 Requires-Dist: lseg-data>=2.1; extra == 'lseg'

{tesorotools_python-0.0.44 → tesorotools_python-0.0.46}/pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
 [project.optional-dependencies]
 bde = ["requests>=2.31"]
 ecb = ["requests>=2.31"]
+imf = ["requests>=2.31", "truststore>=0.10"]
 lseg = ["lseg-data>=2.1"]
 
 [dependency-groups]

{tesorotools_python-0.0.44 → tesorotools_python-0.0.46}/src/tesorotools/__init__.py

@@ -49,9 +49,11 @@ from tesorotools.artists import (
     HorizontalBarChart,
     Legend,
     LinePlot,
+    MatrixChart,
     StackedAreaPlot,
     StackedBarPlot,
     TypeCurve,
+    VectorPlot,
 )
 from tesorotools.orchestration import CompositeRegistry, iter_contexts
 from tesorotools.providers.base import (
@@ -79,6 +81,8 @@ def _register_builtins() -> None:
     register_artist("barh", HorizontalBarChart)
     register_artist("grouped_barh", GroupedBarChart)
     register_artist("type_curve", TypeCurve)
+    register_artist("vector_plot", VectorPlot)
+    register_artist("matrix", MatrixChart)
 
     register_tag("format", Format)
     register_tag("legend", Legend)
@@ -111,6 +115,7 @@ __all__ = [
     "Legend",
     "LinePlot",
     "LSEGProvider",
+    "MatrixChart",
     "RegistryProtocol",
     "Report",
     "Section",
@@ -121,6 +126,7 @@ __all__ = [
     "Text",
     "Title",
     "TypeCurve",
+    "VectorPlot",
     "YamlConstructor",
     "all_artists",
     "all_providers",

{tesorotools_python-0.0.44 → tesorotools_python-0.0.46}/src/tesorotools/artists/__init__.py

@@ -29,8 +29,10 @@ import matplotlib.style
 from tesorotools.artists._common import Artist, Format, Legend
 from tesorotools.artists.barh_plot import GroupedBarChart, HorizontalBarChart
 from tesorotools.artists.line_plot import LinePlot
+from tesorotools.artists.matrix import MatrixChart
 from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
 from tesorotools.artists.type_curve import TypeCurve
+from tesorotools.artists.vector_plot import VectorPlot
 from tesorotools.utils.globals import STYLE_SHEET
 
 matplotlib.style.use(STYLE_SHEET)
@@ -42,7 +44,9 @@ __all__ = [
     "HorizontalBarChart",
     "Legend",
     "LinePlot",
+    "MatrixChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "TypeCurve",
+    "VectorPlot",
 ]

tesorotools_python-0.0.46/src/tesorotools/artists/matrix.py

@@ -0,0 +1,302 @@
+"""Annotated matrix / heatmap-table artist.
+
+Defines :class:`MatrixChart`, the YAML-tag-aware artist
+registered as ``!matrix``.
+
+The chart is a grid of cells -- the "quadrant" or
+segmentation table where each cell is shaded by its value and
+carries a large number plus an optional descriptive label
+(e.g. financial knowledge x digital skill -> "Capacidad
+alta").  Nothing in the implementation is tied to the 2x2
+case: the grid is driven by an ``n_rows x n_cols`` DataFrame,
+so any rectangular layout works (a 3x3 segmentation, a
+5-bucket x 4-bucket transition matrix, ...).
+
+Input is a flat ``pd.DataFrame`` indexed by row id with one
+column per column id -- the same wide shape
+:class:`GroupedBarChart` consumes -- so ``rows`` selects and
+labels the index and ``cols`` selects and labels the columns.
+Cell shading uses a sequential colormap normalised over the
+selected values; text colour flips to stay legible on dark
+cells.  ``NaN`` cells are left blank (no fill, no text), which
+covers triangular or sparse matrices.
+
+Styling constants come from ``PLOT_CONFIG['matrix']``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Self
+
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.colors import Colormap, Normalize
+from matplotlib.figure import Figure
+from matplotlib.patches import Rectangle
+from yaml.nodes import MappingNode
+
+from tesorotools.artists._common import FIG_CONFIG, Format, resolve_data
+from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
+from tesorotools.utils.template import TemplateLoader
+
+__all__ = ["MatrixChart"]
+
+MATRIX_CONFIG: dict[str, Any] = PLOT_CONFIG["matrix"]
+
+
+def _text_color(rgba: tuple[float, float, float, float]) -> str:
+    """Pick a legible text colour for a cell filled with *rgba*.
+
+    Uses relative luminance: dark fills get the light text
+    colour, light fills the dark one.
+    """
+    r, g, b, _a = rgba
+    luminance = 0.299 * r + 0.587 * g + 0.114 * b
+    if luminance < MATRIX_CONFIG["luminance_threshold"]:
+        return MATRIX_CONFIG["light_text"]
+    return MATRIX_CONFIG["dark_text"]
+
+
+class MatrixChart:
+    """Annotated heatmap-table artist (any ``n_rows x n_cols``).
+
+    Parameters
+    ----------
+    out_path
+        ``.png`` path the rendered chart is saved to.
+    data, data_path
+        Provide one.  A wide DataFrame indexed by row id with
+        one column per column id.
+    rows
+        ``id -> label`` for the grid rows, top-to-bottom.
+    cols
+        ``id -> label`` for the grid columns, left-to-right.
+    cell_labels
+        Optional ``{row_id: {col_id: text}}`` descriptive text
+        drawn under each value.  Missing entries draw the
+        value only.
+    scale
+        Multiplier applied to the values (e.g. ``100`` to turn
+        fractions into percentages).
+    fmt
+        :class:`Format` for the big per-cell value.
+    cmap
+        Matplotlib colormap name for the shading (default
+        ``PLOT_CONFIG['matrix']['cmap']``).
+    vmin, vmax
+        Value range mapped to the colormap ends.  Default to
+        the min / max of the selected values.
+    xlabel, ylabel
+        Axis titles (the column / row variable names).
+    figsize
+        Override the figure size; defaults to a square so
+        cells read as tiles.
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        *,
+        data: pd.DataFrame | None = None,
+        data_path: Path | None = None,
+        rows: dict[str, str],
+        cols: dict[str, str],
+        cell_labels: dict[str, dict[str, str]] | None = None,
+        scale: float = 1,
+        fmt: Format | None = None,
+        cmap: str | None = None,
+        vmin: float | None = None,
+        vmax: float | None = None,
+        xlabel: str = "",
+        ylabel: str = "",
+        figsize: tuple[float, float] | None = None,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        if not rows or not cols:
+            raise ValueError("MatrixChart needs at least one row and column")
+        self.out_path = out_path
+        self.data = resolve_data(data, data_path)
+        self.rows = rows
+        self.cols = cols
+        self.cell_labels = cell_labels or {}
+        self.scale = scale
+        self.fmt = fmt or Format()
+        self.cmap = cmap or MATRIX_CONFIG["cmap"]
+        self.vmin = vmin
+        self.vmax = vmax
+        self.xlabel = xlabel
+        self.ylabel = ylabel
+        self.figsize = figsize
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        """Build a :class:`MatrixChart` from the ``!matrix`` YAML tag.
+
+        Required keys
+        -------------
+        ``out_path``
+            ``.png`` destination path.
+        ``data_path``
+            ``.feather`` file with a DataFrame indexed by row
+            id and one column per column id.
+        ``rows`` / ``cols``
+            ``id -> label`` mappings selecting and ordering the
+            grid rows (top-to-bottom) and columns
+            (left-to-right).
+
+        Optional keys (forwarded as-is to ``__init__``)
+        ----------------------------------------------
+        ``cell_labels`` (``{row_id: {col_id: text}}``),
+        ``scale``, ``fmt`` (``!format``), ``cmap``, ``vmin`` /
+        ``vmax``, ``xlabel`` / ``ylabel``, ``figsize``.
+
+        Example
+        -------
+        .. code-block:: yaml
+
+            capacidad: !matrix
+              out_path: out/capacidad.png
+              data_path: data/capacidad.feather
+              xlabel: "Habilidad digital"
+              ylabel: "Conocimientos financieros"
+              fmt: !format {decimals: 1, units: "%"}
+              rows:
+                altos: "Altos"
+                bajos: "Bajos"
+              cols:
+                baja: "Baja"
+                alta: "Alta"
+              cell_labels:
+                altos: {baja: "Solo conocimiento financiero", alta: "Capacidad alta"}
+                bajos: {baja: "Capacidad baja", alta: "Solo habilidad digital"}
+        """
+        cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
+            node, deep=True
+        )
+        cfg.pop("id")
+        cfg["out_path"] = Path(cfg["out_path"])
+        if "data_path" in cfg:
+            cfg["data_path"] = Path(cfg["data_path"])
+        return cls(**cfg)
+
+    def plot(self) -> Axes:
+        """Render the chart and persist it to ``self.out_path``."""
+        row_ids = list(self.rows)
+        col_ids = list(self.cols)
+        missing_rows = [r for r in row_ids if r not in self.data.index]
+        missing_cols = [c for c in col_ids if c not in self.data.columns]
+        if missing_rows or missing_cols:
+            raise KeyError(
+                "MatrixChart ids not found in data — "
+                f"rows: {missing_rows}, cols: {missing_cols}"
+            )
+
+        matrix = self.data.loc[row_ids, col_ids] * self.scale
+        n_rows = len(row_ids)
+
+        values_arr = matrix.to_numpy(dtype=float)
+        valid = values_arr[~np.isnan(values_arr)]
+        vmin = self.vmin if self.vmin is not None else float(valid.min())
+        vmax = self.vmax if self.vmax is not None else float(valid.max())
+        norm = Normalize(vmin=vmin, vmax=vmax)
+        cmap: Colormap = mpl.colormaps[self.cmap]
+
+        fig_kw = dict(FIG_CONFIG)
+        fig_kw["figsize"] = self.figsize if self.figsize is not None else (6, 6)
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **fig_kw
+        )
+        ax: Axes = fig.add_subplot()
+
+        gap: float = MATRIX_CONFIG["gap"]
+        for i, row_id in enumerate(row_ids):
+            # Row 0 sits at the top, so its cell row is the highest y.
+            y_row = n_rows - 1 - i
+            for j, col_id in enumerate(col_ids):
+                value = float(values_arr[i, j])
+                if np.isnan(value):
+                    continue
+                rgba: tuple[float, float, float, float] = cmap(norm(value))
+                ax.add_patch(
+                    Rectangle(
+                        (j + gap / 2, y_row + gap / 2),
+                        1 - gap,
+                        1 - gap,
+                        facecolor=rgba,
+                        edgecolor="none",
+                    )
+                )
+                self._annotate_cell(ax, j + 0.5, y_row + 0.5, value, rgba)
+                label = self.cell_labels.get(row_id, {}).get(col_id)
+                if label:
+                    ax.text(  # type: ignore[reportUnknownMemberType]
+                        j + 0.5,
+                        y_row + 0.5 - MATRIX_CONFIG["label_offset"],
+                        label,
+                        ha="center",
+                        va="center",
+                        color=_text_color(rgba),
+                        fontsize=MATRIX_CONFIG["label_fontsize"],
+                    )
+
+        self._style_axes(ax, row_ids, col_ids)
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            self.out_path
+        )
+        plt.close(fig)
+        return ax
+
+    def _annotate_cell(
+        self,
+        ax: Axes,
+        cx: float,
+        cy: float,
+        value: float,
+        rgba: tuple[float, float, float, float],
+    ) -> None:
+        """Draw the big formatted value near a cell's centre."""
+        ax.text(  # type: ignore[reportUnknownMemberType]
+            cx,
+            cy + MATRIX_CONFIG["value_offset"],
+            format_annotation(value, self.fmt.decimals, self.fmt.units),
+            ha="center",
+            va="center",
+            color=_text_color(rgba),
+            fontsize=MATRIX_CONFIG["value_fontsize"],
+            fontweight=MATRIX_CONFIG["value_weight"],
+        )
+
+    def _style_axes(
+        self, ax: Axes, row_ids: list[str], col_ids: list[str]
+    ) -> None:
+        """Category ticks, axis titles and a frameless look."""
+        n_rows, n_cols = len(row_ids), len(col_ids)
+        ax.set_xlim(0, n_cols)
+        ax.set_ylim(0, n_rows)
+        ax.set_aspect("auto")
+
+        ax.set_xticks([j + 0.5 for j in range(n_cols)])  # type: ignore[reportUnknownMemberType]
+        ax.set_xticklabels(  # type: ignore[reportUnknownMemberType]
+            [self.cols[c] for c in col_ids]
+        )
+        # Row 0 is drawn at the top, so its tick is the highest y.
+        ax.set_yticks([n_rows - 1 - i + 0.5 for i in range(n_rows)])  # type: ignore[reportUnknownMemberType]
+        ax.set_yticklabels(  # type: ignore[reportUnknownMemberType]
+            [self.rows[r] for r in row_ids]
+        )
+        ax.tick_params(  # type: ignore[reportUnknownMemberType]
+            axis="both", length=0
+        )
+        for spine in ax.spines.values():
+            spine.set_visible(False)
+        ax.set_xlabel(  # type: ignore[reportUnknownMemberType]
+            self.xlabel
+        )
+        ax.set_ylabel(  # type: ignore[reportUnknownMemberType]
+            self.ylabel
+        )

tesorotools_python-0.0.46/src/tesorotools/artists/vector_plot.py

@@ -0,0 +1,315 @@
+"""Vector (arrow) chart artist.
+
+Defines :class:`VectorPlot`, the YAML-tag-aware artist
+registered as ``!vector_plot``.
+
+Each entity is drawn as an arrow in a 2D plane from a start
+point to an end point, so a single chart shows how *two*
+variables moved between two periods at once.  The common case
+-- arrows fanning out from the origin, as in the classic
+"public debt vs. bond yield since 2020" chart -- falls out
+when the data already holds the *change* in each variable and
+no start columns are given: the start defaults to ``(0, 0)``.
+
+Unlike the time-series artists, the input DataFrame is indexed
+by entity code (one row per arrow) and the two axes carry two
+different variables, each with its own optional :class:`Format`
+(``x_fmt`` / ``y_fmt``).  Computing the period-over-period
+change is the pipeline's job; this artist only renders the
+pre-computed coordinates.
+
+Layout and the shared ``Format`` / ``Legend`` config holders
+live in :mod:`tesorotools.artists._common`; arrow styling
+constants come from ``PLOT_CONFIG['vector']``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Self
+
+import matplotlib.pyplot as plt
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from matplotlib.ticker import FuncFormatter
+from yaml.nodes import MappingNode
+
+from tesorotools.artists._common import (
+    AX_CONFIG,
+    FIG_CONFIG,
+    Format,
+    resolve_data,
+)
+from tesorotools.utils.matplotlib import PLOT_CONFIG, format_annotation
+from tesorotools.utils.template import TemplateLoader
+
+__all__ = ["VectorPlot"]
+
+VECTOR_CONFIG: dict[str, Any] = PLOT_CONFIG["vector"]
+
+
+class VectorPlot:
+    """Arrow chart showing the change in two variables.
+
+    Each entity in ``series`` is rendered as an arrow from a
+    start point to an end point.  With only ``x`` / ``y``
+    given, arrows start at the origin and their tips encode
+    the change in each variable (the usual "since date X"
+    chart).  Provide ``x_start`` / ``y_start`` to draw arrows
+    between two arbitrary points instead (period-to-period
+    migration in the plane).
+
+    Parameters
+    ----------
+    out_path
+        ``.png`` destination path.
+    data / data_path
+        The source DataFrame (in memory) or a ``.feather``
+        file; exactly one.  Indexed by entity code, one row
+        per arrow.
+    series
+        ``entity_code -> display_label`` mapping.  Selects and
+        orders the rows drawn; the codes must appear in the
+        DataFrame index.
+    x, y
+        Column names holding the arrow-tip coordinates.
+    x_start, y_start
+        Optional column names for the arrow tails.  When
+        omitted the tail sits at ``0`` on that axis.
+    x_scale, y_scale
+        Per-axis multipliers applied to the raw values (e.g.
+        ``100`` to turn rates into basis points).
+    xlabel, ylabel
+        Axis titles.
+    x_fmt, y_fmt
+        Per-axis :class:`Format` controlling tick decimals and
+        units.
+    figsize
+        Optional ``(width, height)`` in inches.
+    series_styles
+        Per-entity matplotlib kwargs for the arrow; ``color``
+        and ``linestyle`` are honoured (``linestyle: dashed``
+        reproduces the dashed arrows used for outliers).
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        *,
+        data: pd.DataFrame | None = None,
+        data_path: Path | None = None,
+        series: dict[str, str],
+        x: str,
+        y: str,
+        x_start: str | None = None,
+        y_start: str | None = None,
+        x_scale: float = 1,
+        y_scale: float = 1,
+        xlabel: str = "",
+        ylabel: str = "",
+        x_fmt: Format | None = None,
+        y_fmt: Format | None = None,
+        figsize: tuple[float, float] | None = None,
+        series_styles: dict[str, dict[str, Any]] | None = None,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        if not series:
+            raise ValueError("VectorPlot needs at least one entity in `series`")
+        self.out_path = out_path
+        self.data = resolve_data(data, data_path)
+        self.series = series
+        self.x = x
+        self.y = y
+        self.x_start = x_start
+        self.y_start = y_start
+        self.x_scale = x_scale
+        self.y_scale = y_scale
+        self.xlabel = xlabel
+        self.ylabel = ylabel
+        self.x_fmt = x_fmt or Format()
+        self.y_fmt = y_fmt or Format()
+        self.figsize = figsize
+        self.series_styles = series_styles or {}
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        """Build a :class:`VectorPlot` from the ``!vector_plot`` YAML tag.
+
+        Required keys
+        -------------
+        ``out_path``
+            ``.png`` destination path.
+        ``data_path``
+            ``.feather`` file indexed by entity code, holding
+            the arrow-tip columns.
+        ``series``
+            ``entity_code -> display_label`` mapping; the codes
+            must appear in the DataFrame index.
+        ``x`` / ``y``
+            Column names for the arrow-tip coordinates.
+
+        Optional keys (forwarded as-is to ``__init__``)
+        ----------------------------------------------
+        ``x_start`` / ``y_start``, ``x_scale`` / ``y_scale``,
+        ``xlabel`` / ``ylabel``, ``x_fmt`` / ``y_fmt``
+        (``!format``), ``figsize``, ``series_styles``.
+
+        Example
+        -------
+        .. code-block:: yaml
+
+            debt_vs_yield: !vector_plot
+              out_path: out/debt_yield.png
+              data_path: data/debt_yield.feather
+              x: debt_change
+              y: yield_change
+              xlabel: "Deuda pública (% PIB), dif. desde ene-2020"
+              ylabel: "Var. tir 10A desde ene-2020"
+              x_fmt: !format {decimals: 1, units: "%"}
+              y_fmt: !format {decimals: 1}
+              series:
+                ES: "ES"
+                DE: "DE"
+                IT: "IT"
+              series_styles:
+                IT: {linestyle: dashed}
+        """
+        cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
+            node, deep=True
+        )
+        cfg.pop("id")
+        cfg["out_path"] = Path(cfg["out_path"])
+        if "data_path" in cfg:
+            cfg["data_path"] = Path(cfg["data_path"])
+        return cls(**cfg)
+
+    def _coords(self, code: str) -> tuple[float, float, float, float]:
+        """Return the ``(x0, y0, x1, y1)`` arrow for *code*, scaled."""
+        row: pd.Series[Any] = self.data.loc[code]  # type: ignore[assignment]
+        x1 = float(row[self.x]) * self.x_scale
+        y1 = float(row[self.y]) * self.y_scale
+        x0 = float(row[self.x_start]) * self.x_scale if self.x_start else 0.0
+        y0 = float(row[self.y_start]) * self.y_scale if self.y_start else 0.0
+        return x0, y0, x1, y1
+
+    def plot(self) -> Axes:
+        needed = [self.x, self.y]
+        if self.x_start is not None:
+            needed.append(self.x_start)
+        if self.y_start is not None:
+            needed.append(self.y_start)
+        missing = [c for c in needed if c not in self.data.columns]
+        if missing:
+            raise KeyError(
+                f"VectorPlot columns not found in data: {missing}. "
+                f"Available: {list(self.data.columns)}"
+            )
+        unknown = [c for c in self.series if c not in self.data.index]
+        if unknown:
+            raise KeyError(
+                f"VectorPlot series codes not in data index: {unknown}"
+            )
+
+        fig_kw = dict(FIG_CONFIG)
+        if self.figsize is not None:
+            fig_kw["figsize"] = self.figsize
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **fig_kw
+        )
+        ax: Axes = fig.add_subplot()
+
+        cycle: list[str] = plt.rcParams["axes.prop_cycle"].by_key()["color"]
+        xs: list[float] = [0.0]
+        ys: list[float] = [0.0]
+        for i, code in enumerate(self.series):
+            x0, y0, x1, y1 = self._coords(code)
+            xs.extend((x0, x1))
+            ys.extend((y0, y1))
+            style = self.series_styles.get(code, {})
+            color: Any = style.get("color", cycle[i % len(cycle)])
+            linestyle: Any = style.get("linestyle", "solid")
+            ax.annotate(  # type: ignore[reportUnknownMemberType]
+                "",
+                xy=(x1, y1),
+                xytext=(x0, y0),
+                arrowprops={
+                    "arrowstyle": VECTOR_CONFIG["arrowstyle"],
+                    "color": color,
+                    "linestyle": linestyle,
+                    "linewidth": VECTOR_CONFIG["linewidth"],
+                    "mutation_scale": VECTOR_CONFIG["mutation_scale"],
+                    "shrinkA": 0,
+                    "shrinkB": 0,
+                },
+            )
+            pad: float = VECTOR_CONFIG["label_pad"]
+            ax.annotate(  # type: ignore[reportUnknownMemberType]
+                self.series[code],
+                xy=(x1, y1),
+                xytext=(
+                    pad if x1 >= x0 else -pad,
+                    pad if y1 >= y0 else -pad,
+                ),
+                textcoords="offset points",
+                color=color,
+                ha="left" if x1 >= x0 else "right",
+                va="bottom" if y1 >= y0 else "top",
+            )
+
+        self._style_axes(ax, xs, ys)
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            self.out_path
+        )
+        plt.close(fig)
+        return ax
+
+    def _style_axes(self, ax: Axes, xs: list[float], ys: list[float]) -> None:
+        """Frame, origin cross-hairs, tick formatters and labels."""
+        margin: float = VECTOR_CONFIG["margin"]
+        _set_limits(ax.set_xlim, xs, margin)
+        _set_limits(ax.set_ylim, ys, margin)
+
+        center = dict(VECTOR_CONFIG["center_line"])
+        ax.axvline(  # type: ignore[reportUnknownMemberType]
+            x=0, **center
+        )
+        ax.axhline(  # type: ignore[reportUnknownMemberType]
+            y=0, **AX_CONFIG["baseline"]
+        )
+
+        spines = AX_CONFIG["spines"]
+        for spine in ax.spines.values():
+            spine.set_color(spines["color"])
+            spine.set_linewidth(spines["linewidth"])
+
+        def _fmt_x(v: float, _pos: int) -> str:
+            return format_annotation(v, self.x_fmt.decimals, self.x_fmt.units)
+
+        def _fmt_y(v: float, _pos: int) -> str:
+            return format_annotation(v, self.y_fmt.decimals, self.y_fmt.units)
+
+        ax.xaxis.set_major_formatter(FuncFormatter(_fmt_x))
+        ax.yaxis.set_major_formatter(FuncFormatter(_fmt_y))
+        ax.set_xlabel(  # type: ignore[reportUnknownMemberType]
+            self.xlabel
+        )
+        ax.set_ylabel(  # type: ignore[reportUnknownMemberType]
+            self.ylabel
+        )
+        for tick in (*ax.get_xticklines(), *ax.get_yticklines()):
+            tick.set_markeredgecolor(spines["color"])
+
+
+def _set_limits(setter: Any, values: list[float], margin: float) -> None:
+    """Set an axis range to span *values* with *margin* padding.
+
+    The origin is always included (the caller seeds ``values``
+    with ``0``).  A degenerate span collapses to ``±1`` so the
+    arrow stays visible.
+    """
+    lo, hi = min(values), max(values)
+    span = hi - lo
+    pad = span * margin if span > 0 else 1.0
+    setter(lo - pad, hi + pad)