tesorotools-python 0.0.44__py3-none-any.whl → 0.0.46__py3-none-any.whl

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/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/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/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)

tesorotools/assets/plots.yaml

@@ -29,6 +29,30 @@ type_curve:
     marker: D
     color: C0
 
+vector:
+  linewidth: 2
+  arrowstyle: "-|>"
+  mutation_scale: 14   # arrow-head size in points
+  label_pad: 5         # gap (points) between arrow head and its label
+  margin: 0.15         # fraction of the data range left as padding
+  center_line:
+    color: gray
+    linestyle: dashed
+    linewidth: 1
+    zorder: 1
+
+matrix:
+  cmap: Blues
+  gap: 0.04              # white gutter between cells (fraction of a cell)
+  value_fontsize: 26
+  label_fontsize: 13
+  value_weight: bold
+  light_text: white      # value/label colour on dark cells
+  dark_text: "#1a1a1a"   # value/label colour on light cells
+  luminance_threshold: 0.55
+  value_offset: 0.08     # value sits this fraction of a cell above centre
+  label_offset: 0.14     # label sits this fraction of a cell below centre
+
 barh:
   highlight_factor: 0.4
   padding: 5

tesorotools/providers/__init__.py

@@ -1,9 +1,10 @@
 """Public provider API.
 
-``BdeProvider``, ``EcbProvider`` and ``LSEGProvider`` depend on
-the optional ``[bde]`` / ``[ecb]`` / ``[lseg]`` extras and are
-imported lazily through ``__getattr__``; importing
-``tesorotools.providers`` itself does not require those extras.
+``BdeProvider``, ``EcbProvider``, ``ImfIrfclProvider`` and
+``LSEGProvider`` depend on the optional ``[bde]`` / ``[ecb]`` /
+``[imf]`` / ``[lseg]`` extras and are imported lazily through
+``__getattr__``; importing ``tesorotools.providers`` itself does not
+require those extras.
 """
 
 from typing import TYPE_CHECKING, Any
@@ -17,12 +18,14 @@ from tesorotools.providers.base import (
 if TYPE_CHECKING:
     from tesorotools.providers.bde import BdeProvider
     from tesorotools.providers.ecb import EcbProvider
+    from tesorotools.providers.imf_irfcl import ImfIrfclProvider
     from tesorotools.providers.lseg import LSEGProvider
 
 __all__ = [
     "BdeProvider",
     "DataProvider",
     "EcbProvider",
+    "ImfIrfclProvider",
     "LSEGProvider",
     "RegistryProtocol",
     "bootstrap_providers",
@@ -38,6 +41,10 @@ def __getattr__(name: str) -> Any:
         from tesorotools.providers.ecb import EcbProvider
 
         return EcbProvider
+    if name == "ImfIrfclProvider":
+        from tesorotools.providers.imf_irfcl import ImfIrfclProvider
+
+        return ImfIrfclProvider
     if name == "LSEGProvider":
         from tesorotools.providers.lseg import LSEGProvider
 

tesorotools/providers/imf_irfcl.py

@@ -0,0 +1,242 @@
+"""IMF IRFCL data provider via the official SDMX 3.0 REST API.
+
+Downloads time series from the IMF's IRFCL dataflow (International
+Reserves and Foreign Currency Liquidity), which publishes official
+reserve assets per country, gold included.  No authentication
+required.
+
+Install with the ``imf`` optional extra::
+
+    uv pip install "tesorotools-python[imf]"
+
+Indicators (verified against the API in jun-2026):
+
+* ``IRFCLDT1_IRFCL56V_FTO`` — gold, VOLUME in fine troy ounces.  This
+  is the **physical stock** (despite the IMF label saying "millions of
+  ounces", the raw value comes in ounces: Spain ≈ 9,053,750 oz ≈
+  281.6 t).
+* ``IRFCLDT1_IRFCL56_USD`` — gold value in USD (approx. market value).
+* ``IRFCLDT1_IRFCL65_USD`` — TOTAL official reserve assets in USD
+  (denominator of the % gold represents over reserves).
+
+API base
+--------
+``https://api.imf.org/external/sdmx/3.0/data/dataflow/IMF.STA/IRFCL/~/{key}``
+
+Code convention (4 dimensions of DSD_IRFCL_PUB)
+-----------------------------------------------
+::
+
+    {COUNTRY}.{INDICATOR}.{SECTOR}.{FREQUENCY}
+
+* COUNTRY    ISO-3 country code (``ESP``, ``USA``, ``DEU`` …).
+* INDICATOR  the IRFCL indicator (``IRFCLDT1_IRFCL56V_FTO`` …).
+* SECTOR     ``*`` (wildcard).  Countries report gold under different
+             sectors (Spain ``S1X``, the US ``S1XS1311`` …); the
+             wildcard captures them all.  When a key returns several
+             series (same gold total under different sectors) they are
+             collapsed by date in :meth:`_fetch_one` (last write wins;
+             values coincide).
+* FREQUENCY  ``M`` (monthly; reserves are published every month).
+
+Keys are passed verbatim to the API; this provider does not parse them.
+
+Date label
+----------
+IRFCL labels the period and the observation is the end-of-period
+balance.  We map to the real end of period:
+
+* ``"2026"``     → 2026-12-31
+* ``"2026-Q1"``  → 2026-03-31
+* ``"2026-M04"`` → 2026-04-30
+
+Corporate TLS
+-------------
+``truststore`` is enabled on import (if installed) so the provider
+works behind MINECO's TLS proxy without ``verify=False``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar
+
+import pandas as pd
+import requests
+
+from tesorotools.providers.base import DataProvider
+
+logger = logging.getLogger(__name__)
+
+
+def _enable_truststore_once() -> bool:
+    """Enable truststore (the OS cert store) if available."""
+    try:
+        import truststore  # type: ignore[import-not-found]
+    except ImportError:
+        return False
+    truststore.inject_into_ssl()  # pyright: ignore[reportUnknownMemberType]
+    return True
+
+
+_TRUSTSTORE_ACTIVE = _enable_truststore_once()
+
+_API_BASE = (
+    "https://api.imf.org/external/sdmx/3.0/data/dataflow/IMF.STA/IRFCL/~"
+)
+_DEFAULT_TIMEOUT = 60
+_DEFAULT_START = "2000"
+_HEADERS = {"Accept": "application/vnd.sdmx.data+json"}
+
+
+class ImfIrfclProvider(DataProvider):
+    """Provider that downloads IMF IRFCL series via SDMX 3.0.
+
+    One HTTP request per key.  Series with no observations (a country
+    that does not report that indicator) are skipped with a warning
+    instead of aborting the whole download.
+
+    Parameters
+    ----------
+    timeout
+        Max seconds per HTTP request.
+    session
+        Optional pre-built ``requests.Session``.  Useful for tests or
+        for custom retry policies.
+    """
+
+    PROVIDER_NAME: ClassVar[str] = "imf_irfcl"
+
+    def __init__(
+        self,
+        *,
+        timeout: int = _DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ) -> None:
+        self._timeout = timeout
+        self._session = session or requests.Session()
+
+    def fetch(
+        self,
+        codes: list[str],
+        start: str | None = None,
+        end: str | None = None,
+    ) -> pd.DataFrame:
+        """Download a list of IRFCL keys and return a wide DataFrame.
+
+        Parameters
+        ----------
+        codes
+            List of IRFCL keys (``"{COUNTRY}.{INDICATOR}.{SECTOR}.{FREQ}"``).
+        start
+            Start period (e.g. ``"2024"``).  If ``None`` defaults to
+            ``"2000"``.
+        end
+            End date as ISO string.  If ``None`` up to latest.
+
+        Returns
+        -------
+        pd.DataFrame
+            Wide DataFrame. Index = dates (tz-naive), columns = the
+            requested codes. Missing observations are NaN.
+        """
+        if not codes:
+            return pd.DataFrame()
+
+        cols: dict[str, pd.Series[float]] = {}
+        for code in codes:
+            try:
+                series = self._fetch_one(code, start=start)
+            except requests.RequestException as e:
+                logger.warning("IRFCL: failed downloading %s (%s)", code, e)
+                continue
+            if series is not None and not series.empty:
+                cols[code] = series
+
+        if not cols:
+            return pd.DataFrame()
+
+        df = pd.DataFrame(cols).sort_index()
+        df.index.name = "date"
+        if end:
+            df = df.loc[df.index <= pd.Timestamp(end)]
+        return df
+
+    def is_available(self) -> bool:
+        """Check whether the IMF API responds.
+
+        Hits a small ESP gold-volume query.
+        """
+        try:
+            r = self._session.get(
+                f"{_API_BASE}/ESP.IRFCLDT1_IRFCL56V_FTO.*.M?startPeriod=2024",
+                timeout=10,
+                headers=_HEADERS,
+            )
+            return r.status_code == 200
+        except requests.RequestException:
+            return False
+
+    def _fetch_one(
+        self, code: str, start: str | None = None
+    ) -> "pd.Series[float] | None":
+        """Download a single IRFCL series and return it as a Series."""
+        url = f"{_API_BASE}/{code}?startPeriod={start or _DEFAULT_START}"
+        r = self._session.get(url, timeout=self._timeout, headers=_HEADERS)
+        if r.status_code != 200:
+            logger.warning("IRFCL: HTTP %d for %s", r.status_code, code)
+            return None
+        payload = r.json()
+        data_sets = payload.get("data", {}).get("dataSets", [])
+        structures = payload.get("data", {}).get("structures", [])
+        if not data_sets or not structures:
+            return None
+        time_dim = structures[0].get("dimensions", {}).get("observation", [])
+        if not time_dim:
+            return None
+        time_values = [t["value"] for t in time_dim[0].get("values", [])]
+        series_dict = data_sets[0].get("series", {})
+
+        data: dict[pd.Timestamp, float] = {}
+        for _, series in series_dict.items():
+            observations = series.get("observations", {})
+            for idx_str, payload_obs in observations.items():
+                if not payload_obs or payload_obs[0] is None:
+                    continue
+                try:
+                    value = float(payload_obs[0])
+                except (TypeError, ValueError):
+                    continue
+                idx = int(idx_str)
+                if idx >= len(time_values):
+                    continue
+                ts = _parse_period(time_values[idx])
+                if ts is not None:
+                    data[ts] = value
+
+        if not data:
+            return None
+        return pd.Series(data, dtype="float64").sort_index()
+
+
+def _parse_period(label: str) -> pd.Timestamp | None:
+    """Convert an IRFCL label to the **real end of period**.
+
+    * ``"YYYY"``     → December 31 of that year.
+    * ``"YYYY-QN"``  → last day of the quarter.
+    * ``"YYYY-MNN"`` → last day of the month.
+    """
+    try:
+        if "-Q" in label:
+            period = pd.Period(label.replace("-Q", "Q"), freq="Q")
+            return period.end_time.normalize()
+        if "-M" in label:  # "YYYY-MNN"
+            year_str, month_str = label.split("-M")
+            period = pd.Period(
+                freq="M", year=int(year_str), month=int(month_str)
+            )
+            return period.end_time.normalize()
+        year = int(label)
+        return pd.Timestamp(year=year, month=12, day=31)
+    except (ValueError, TypeError):
+        return None

{tesorotools_python-0.0.44.dist-info → tesorotools_python-0.0.46.dist-info}/METADATA

@@ -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.dist-info → tesorotools_python-0.0.46.dist-info}/RECORD

@@ -1,18 +1,20 @@
-tesorotools/__init__.py,sha256=a7IzgMbmbJYnaS3vEQ_lNacqrS0cSBoU4Uz5qIAhb_4,3761
+tesorotools/__init__.py,sha256=YsyE_aq7DdDs__6VPkKsy0exmXZpig0ieoD-ejuT0p0,3921
 tesorotools/_build_context.py,sha256=MH2AKjkwuubN__sBQoXbfTD1bh5RE6w9l5yUFxkJxy8,1982
 tesorotools/_registry.py,sha256=ZJOr7jACxykvzoepebZDiJdTcR37Q3X-DQ07lm9ZYB0,7975
 tesorotools/driver.py,sha256=qEVhLYanbG7VXe3WrCCD0RJV_0X4xzhalrfABPB1gSI,5016
 tesorotools/manifest.py,sha256=UeUURo_yQtCnXaYDUhNyxHaRlH4eNSh6szIYlv-PQZs,3346
 tesorotools/orchestration.py,sha256=24C-LTM4uy7eckjXBjJbC2t92fg6yffl5H-E9Gm2W9M,3442
 tesorotools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tesorotools/artists/__init__.py,sha256=iabMiHj7ZzXt5myhIcnYew7W_xc0IJc-NiBy9UnDEs8,1487
+tesorotools/artists/__init__.py,sha256=GR9_wnpH8dDCdIBIB-Psd4_NtdL9nu9vYpCHcU9IdUE,1630
 tesorotools/artists/_common.py,sha256=y5XfDcsRxH3ydFgyphE2icppPAGsxUEPoxH5ikOoI3c,16403
 tesorotools/artists/barh_plot.py,sha256=T68Vs8lPkhTVgkQZkK4X9s1-Eeipumm7Li7YOgItHxM,20187
 tesorotools/artists/line_plot.py,sha256=EnILDic5T5keBOpKQ9Hzrb5ErcMEzNm8IFR_lXxINDE,9553
+tesorotools/artists/matrix.py,sha256=mx7fRIydttXuZmDzj2jzN3cUm98oawAwjSvjS50xrpE,11005
 tesorotools/artists/stacked.py,sha256=gcY0DNxDAnF9laGMLFMxYDuG95Ab8SykCQfPTzeQync,13447
 tesorotools/artists/type_curve.py,sha256=7yidpNOs4Q7IFMwKRM2-6lNKRTV54A0ImM0DK1xSSoM,8968
+tesorotools/artists/vector_plot.py,sha256=q0Rww-wUZuZQuB3IV9bQx8v0yrYWJj3Ns7oOrq-UwFo,11393
 tesorotools/assets/README.md,sha256=EjDuA4Xf-Omn0Khp8erNXdW-iyWBzSM2FQFexdrS6Eg,285
-tesorotools/assets/plots.yaml,sha256=rE4NuMe3v0uTDnFt8GfJ3jC4WfXxu2wlr--tdkfWLi4,648
+tesorotools/assets/plots.yaml,sha256=yfpK9TGznZzOqhNteM253Aq8sOmn8s8fKVerfAC-Ais,1426
 tesorotools/assets/tesoro.mplstyle,sha256=HN7o04zzgwL2R6GeMvQlj-rBI_lutCwdvqwPKYyv9Tg,456
 tesorotools/assets/fonts/CabinetGrotesk-Black.otf,sha256=b7M_yFxz5IcGtmWWPMzLVkfx4RLhVALQDFeoq4T1YD0,37728
 tesorotools/assets/fonts/CabinetGrotesk-Bold.otf,sha256=86oM6a9QVAjZoEIFFcbCbcIVEwtWrMBX0ks7_CzaKS4,38148
@@ -39,10 +41,11 @@ tesorotools/pipeline/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hS
 tesorotools/pipeline/diagnose.py,sha256=Ji_T3rAn-z4NhSdkpyPsnwQ1CTl4u5-1gnJZC8d1Sxg,1470
 tesorotools/pipeline/engine.py,sha256=D4gKIv1bO6pw2gUMWJ7CVRv7e_kWWrWpZCzupeZCx0k,2929
 tesorotools/pipeline/rules.py,sha256=OXi6dk2Gx63aO-SGjYnblhAah7tQIynNq2DKtfMGIEk,10041
-tesorotools/providers/__init__.py,sha256=uSer9cXywNBA4K7gfkon7d5JoXEkrP5sBEIw5YoW35I,1235
+tesorotools/providers/__init__.py,sha256=7iEs_BeNeVSMwzjsVd16b6GRmj3bgzMD30rNLEKwupo,1495
 tesorotools/providers/base.py,sha256=6PA1HKhbc-Ehy27Ekm4wn-jWthEdL39Q9qxLCoqH_Jo,7666
 tesorotools/providers/bde.py,sha256=wVfaKzgInTjThJ_twQ-ycA6FUMAKLx3BWL19P03LR0g,7226
 tesorotools/providers/ecb.py,sha256=8UIW-NFLlGVIM7E2Sd_9UEWryt5wwilY3Hv13dnjY68,6422
+tesorotools/providers/imf_irfcl.py,sha256=jGUDFGJBpNRsWKRI90BzI5AzIOmrSj6XwBS6ZUThc8A,8041
 tesorotools/providers/lseg.py,sha256=paKdSxb1tWv26YCwMD0dEUfF4GLFJWzHukKII9WPges,30183
 tesorotools/render/__init__.py,sha256=cqC5hoOwt_ZEE7gNG8nBbvf59YI99Lro8e18WsMKVT0,589
 tesorotools/render/report.py,sha256=_7QnmDgUScRtUWSuaKYoTOVk2TTGUCkRWxAo1haxnek,1051
@@ -64,6 +67,6 @@ tesorotools/utils/matplotlib.py,sha256=lItlkJwJEDGALt0J1UZioTz2GOOFPPe7ffQ4Hzxl7
 tesorotools/utils/series.py,sha256=AEf5DhneYjzQ0nvZD5b1IU3hop0Xgb3Bw2xWs_G3Lhw,1207
 tesorotools/utils/shortcuts.py,sha256=9fpTLgfDFm6_1kh2W0Zk2atn3ZIZMvPfuOjlPpjVy4c,1718
 tesorotools/utils/template.py,sha256=owYVB_dDlkIcKGmT6muH_4UjKDD7JYn_I1pxjQ9VIB8,5211
-tesorotools_python-0.0.44.dist-info/METADATA,sha256=hsbxz4y6lPP0IplST5yGfmOCjIltXx1rFMh0XFTk96w,610
-tesorotools_python-0.0.44.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-tesorotools_python-0.0.44.dist-info/RECORD,,
+tesorotools_python-0.0.46.dist-info/METADATA,sha256=9hoqw47cZa0TQiDwpT93d6TDnWHOCWi2nM_KxFuXhfU,724
+tesorotools_python-0.0.46.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tesorotools_python-0.0.46.dist-info/RECORD,,