tesorotools-python 0.0.49__tar.gz → 0.0.50__tar.gz

{tesorotools_python-0.0.49 → tesorotools_python-0.0.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.49
+Version: 0.0.50
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.0.49 → tesorotools_python-0.0.50}/src/tesorotools/__init__.py

@@ -17,8 +17,17 @@ plural variants).  See ``docs/extending.md`` for the
 recommended idioms.
 """
 
+from importlib.metadata import PackageNotFoundError, version
 from typing import TYPE_CHECKING, Any
 
+try:
+    #: Installed distribution version (set by hatch-vcs from the git tag).
+    #: Falls back to ``"0.0.0"`` when the package is not installed (e.g.
+    #: running straight from a source checkout with no metadata).
+    __version__ = version("tesorotools-python")
+except PackageNotFoundError:  # pragma: no cover - source-only checkout
+    __version__ = "0.0.0"
+
 if TYPE_CHECKING:
     from tesorotools.providers.bde import BdeProvider
     from tesorotools.providers.ecb import EcbProvider
@@ -50,6 +59,7 @@ from tesorotools.artists import (
     Legend,
     LinePlot,
     MatrixChart,
+    ShockChart,
     StackedAreaPlot,
     StackedBarPlot,
     TypeCurve,
@@ -85,6 +95,7 @@ def _register_builtins() -> None:
     register_artist("type_curve", TypeCurve)
     register_artist("vector_plot", VectorPlot)
     register_artist("matrix", MatrixChart)
+    register_artist("shock_plot", ShockChart)
     register_artist("waterfall", Waterfall)
 
     register_tag("format", Format)
@@ -103,6 +114,7 @@ _register_builtins()
 
 
 __all__ = [
+    "__version__",
     "Artist",
     "BdeProvider",
     "BuildContext",
@@ -122,6 +134,7 @@ __all__ = [
     "RegistryProtocol",
     "Report",
     "Section",
+    "ShockChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "Subtitle",

{tesorotools_python-0.0.49 → tesorotools_python-0.0.50}/src/tesorotools/artists/__init__.py

@@ -29,6 +29,7 @@ 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.shock_plot import ShockChart
 from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
 from tesorotools.artists.type_curve import TypeCurve
 from tesorotools.artists.vector_plot import VectorPlot
@@ -42,6 +43,7 @@ __all__ = [
     "Legend",
     "LinePlot",
     "MatrixChart",
+    "ShockChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "TypeCurve",

{tesorotools_python-0.0.49 → tesorotools_python-0.0.50}/src/tesorotools/artists/line_plot.py

@@ -57,8 +57,16 @@ class LinePlot:
     ``plot_size``).  Line-specific knobs:
 
     * ``base_100`` / ``base_100_date`` -- rebase every series
-      to 100 at the first row, or at the row nearest the
-      given date.
+      *multiplicatively* to 100 at the first row, or at the
+      row nearest the given date (the index form).
+    * ``base_0`` / ``base_0_date`` -- rebase every series
+      *subtractively* to 0: the plotted value is the change
+      since the anchor row (first row, or the row nearest the
+      given date), ``(value - anchor)``. ``scale`` still maps
+      the raw change to the display unit (e.g. ``scale: 100``
+      with ``units: "p.b."`` for the move in basis points
+      since an event). Mutually exclusive with ``base_100``;
+      pair with ``baseline: true`` to draw the zero line.
     * ``annotate`` / ``annotate_color`` -- label the last
       non-NaN value next to each line; with packing so
       labels do not overlap.
@@ -118,6 +126,8 @@ class LinePlot:
         end_date: datetime.datetime | None = None,
         base_100: bool = False,
         base_100_date: datetime.datetime | str | None = None,
+        base_0: bool = False,
+        base_0_date: datetime.datetime | str | None = None,
         annotate: bool = False,
         annotate_color: str | None = None,
         baseline: bool = False,
@@ -136,6 +146,12 @@ class LinePlot:
     ) -> None:
         if out_path.suffix != ".png":
             raise ValueError(f"out_path must be .png: {out_path}")
+        if base_100 and base_0:
+            raise ValueError(
+                "base_100 and base_0 are mutually exclusive: a series is "
+                "either rebased multiplicatively (index) or subtractively "
+                "(change-since), not both"
+            )
         self.out_path = out_path
         self.data = resolve_data(data, data_path)
         self.series = series
@@ -145,6 +161,8 @@ class LinePlot:
         self.end_date = end_date
         self.base_100 = base_100
         self.base_100_date = base_100_date
+        self.base_0 = base_0
+        self.base_0_date = base_0_date
         self.annotate = annotate
         self.annotate_color = annotate_color
         self.baseline = baseline
@@ -179,7 +197,8 @@ class LinePlot:
         Optional keys (forwarded as-is to ``__init__``)
         ----------------------------------------------
         ``scale``, ``start_date``, ``end_date``, ``base_100``,
-        ``base_100_date``, ``annotate``, ``annotate_color``,
+        ``base_100_date``, ``base_0``, ``base_0_date``,
+        ``annotate``, ``annotate_color``,
         ``baseline``, ``fmt`` (``!format``), ``legend``
         (``!legend``), ``figsize``, ``series_styles``,
         ``plot_size``, ``vlines``, ``compact``, ``font_pt``,
@@ -236,11 +255,18 @@ class LinePlot:
 
         plot_data = plot_data * self.scale
 
-        if self.base_100:
-            if self.base_100_date is None:
+        if self.base_100 or self.base_0:
+            # shared anchor lookup: the first row, or the row at the nearest
+            # index date to the requested anchor date. base_100 rebases
+            # multiplicatively (ratio -> index 100); base_0 subtractively
+            # (difference -> change since the anchor, baseline 0).
+            anchor_date = (
+                self.base_100_date if self.base_100 else self.base_0_date
+            )
+            if anchor_date is None:
                 anchor: pd.Series[float] = plot_data.iloc[0, :]
             else:
-                anchor_ts: pd.Timestamp = pd.to_datetime(self.base_100_date)
+                anchor_ts: pd.Timestamp = pd.to_datetime(anchor_date)
                 idx_pos: int = self.data.index.get_indexer(
                     pd.Index([anchor_ts]), method="nearest"
                 )[0]
@@ -248,7 +274,10 @@ class LinePlot:
                     self.data.iloc[idx_pos, :].loc[list(self.series.keys())]
                     * self.scale
                 )
-            plot_data = plot_data / anchor * 100
+            if self.base_100:
+                plot_data = plot_data / anchor * 100
+            else:
+                plot_data = plot_data - anchor
 
         fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
             **compact_figure_kwargs(self.compact, self.figsize)

tesorotools_python-0.0.50/src/tesorotools/artists/shock_plot.py

@@ -0,0 +1,333 @@
+"""Per-shock aftermath chart artist, registered as ``!shock_plot``.
+
+Plots **one** asset across **N** shock events, each window reindexed to
+days-relative-to-the-event so the aftermaths overlay on a common x-axis
+(0 = the shock day). Historical shocks draw in ``C2`` with rotating
+linestyles; the most recent (last in dict order) is highlighted in
+``C0`` (solid).
+
+Two rebases, mirroring :class:`LinePlot`:
+
+* ``base100`` (the default) -- normalise each window *multiplicatively*
+  to 100 at its anchor, so every aftermath reads as an index.
+* ``base100: false`` -- the *subtractive* form: the plotted value is the
+  change since the anchor, ``(value - anchor)``, with ``scale`` mapping
+  the raw move to the display unit (e.g. ``scale: 100`` + ``units:
+  "p.b."`` for the move in basis points since the event). The 0 baseline
+  is drawn here.
+
+Layout and styling come entirely from
+:mod:`tesorotools.artists._common`, so the chart matches the other image
+artists (``style_spines`` / ``style_baseline`` for the frame, the compact
+toolkit for the two-per-row size, ``place_legend`` for legend packing).
+
+Render lifecycle mirrors :class:`LinePlot`: ``build()`` returns
+``(Figure, Axes)`` in memory; ``save(fig)`` persists to ``out_path``;
+``plot()`` does both.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Self, cast
+
+import matplotlib.pyplot as plt
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from pandas.tseries.offsets import BDay
+from yaml.nodes import MappingNode
+
+from tesorotools.artists._common import (
+    AX_CONFIG,
+    Format,
+    Legend,
+    compact_figure_kwargs,
+    compact_font_pt,
+    dynamic_dpi,
+    place_legend,
+    resolve_data,
+    style_baseline,
+    style_compact_axes,
+    style_spines,
+)
+from tesorotools.utils.template import TemplateLoader
+
+__all__ = ["ShockChart"]
+
+
+@dataclass(frozen=True)
+class _ShockEvent:
+    date: str
+    days_before: int
+    days_after: int
+
+
+def _normalize_shocks(
+    shocks: dict[str, Any],
+    default_before: int,
+    default_after: int,
+) -> dict[str, _ShockEvent]:
+    """Translate the YAML ``shocks`` dict into per-event records.
+
+    Each entry maps a label to either the simple string form
+    (``"YYYY-MM-DD"``) -- in which case the chart-level ``shock_pre`` /
+    ``shock_cooldown`` apply -- or the extended dict form
+    (``{date, days_before, days_after}``) for per-shock window overrides.
+    """
+    out: dict[str, _ShockEvent] = {}
+    for name, spec in shocks.items():
+        if isinstance(spec, str):
+            out[name] = _ShockEvent(
+                date=spec,
+                days_before=default_before,
+                days_after=default_after,
+            )
+        elif isinstance(spec, dict):
+            spec_dict = cast("dict[str, Any]", spec)
+            if "date" not in spec_dict:
+                raise ValueError(
+                    f"Shock {name!r}: extended form requires a 'date' key"
+                )
+            out[name] = _ShockEvent(
+                date=str(spec_dict["date"]),
+                days_before=int(spec_dict.get("days_before", default_before)),
+                days_after=int(spec_dict.get("days_after", default_after)),
+            )
+        else:
+            raise TypeError(
+                f"Shock {name!r}: spec must be a date string or a dict, "
+                f"got {type(spec).__name__}"
+            )
+    return out
+
+
+class ShockChart:
+    """One asset reindexed across N shocks; x-axis = days from event.
+
+    Parameters mirror the other image artists where they overlap
+    (``out_path``, ``data`` / ``data_path``, ``scale``, ``fmt``,
+    ``legend``, ``figsize``, ``compact``).  Shock-specific knobs:
+
+    * ``asset`` -- the single column of ``data`` to follow.
+    * ``shocks`` -- ``label -> spec`` mapping; each spec is either a
+      ``"YYYY-MM-DD"`` string (using the chart-level window) or a
+      ``{date, days_before, days_after}`` dict for per-shock overrides.
+    * ``shock_pre`` / ``shock_cooldown`` -- default window (business
+      days before / after the event) for the string-form shocks.
+    * ``base100`` -- ``True`` (default) rebases each window to 100
+      multiplicatively; ``False`` plots ``(value - anchor) * scale`` and
+      draws the 0 baseline (e.g. p.b. since the event).
+    * ``common_anchor`` -- rebase every window against one shock's anchor
+      value instead of each window's own anchor; must be a shock label.
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        *,
+        data: pd.DataFrame | None = None,
+        data_path: Path | None = None,
+        asset: str,
+        shocks: dict[str, Any],
+        scale: float = 1,
+        shock_cooldown: int = 60,
+        shock_pre: int = 30,
+        base100: bool = True,
+        common_anchor: str | None = None,
+        fmt: Format | None = None,
+        legend: Legend | None = None,
+        figsize: tuple[float, float] | None = None,
+        compact: bool = False,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        self.out_path = out_path
+        self.data = resolve_data(data, data_path)
+        self.asset = asset
+        self.scale = scale
+        self.shock_cooldown = shock_cooldown
+        self.shock_pre = shock_pre
+        self.base100 = base100
+        self.fmt = fmt or Format()
+        self.legend = legend
+        self.figsize = figsize
+        self.compact = compact
+        self._events = _normalize_shocks(shocks, shock_pre, shock_cooldown)
+        if common_anchor is not None and common_anchor not in self._events:
+            raise ValueError(
+                f"common_anchor {common_anchor!r} must match one of the "
+                f"shock labels: {list(self._events)}"
+            )
+        self.common_anchor = common_anchor
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        """Build a :class:`ShockChart` from the ``!shock_plot`` YAML tag.
+
+        Required keys
+        -------------
+        ``out_path``
+            ``.png`` destination path.
+        ``data_path``
+            ``.feather`` file with daily observations
+            (DatetimeIndex x asset columns).
+        ``asset``
+            column of the loaded DataFrame to follow.
+        ``shocks``
+            ``label -> spec`` mapping (string date or
+            ``{date, days_before, days_after}`` dict).
+
+        Optional keys (forwarded as-is to ``__init__``)
+        ----------------------------------------------
+        ``scale``, ``shock_pre``, ``shock_cooldown``,
+        ``base100``, ``common_anchor``, ``fmt`` (``!format``),
+        ``legend`` (``!legend``), ``figsize``, ``compact``.
+
+        Example
+        -------
+        .. code-block:: yaml
+
+            ust_10y_shocks: !shock_plot
+              out_path: out/ust_shocks.png
+              data_path: data/rates.feather
+              asset: UST10Y
+              base100: false
+              scale: 100
+              fmt: !format {decimals: 0, units: "p.b."}
+              legend: !legend {}
+              shocks:
+                "Elecciones EE.UU.": "2024-11-05"
+                "Liberation Day": {date: "2025-04-02", days_after: 90}
+        """
+        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 build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; return ``(fig, ax)`` without saving."""
+        selected: pd.Series[float] = self.data.loc[:, self.asset] * self.scale
+
+        if self.common_anchor is not None:
+            anchor_value = selected.loc[self._events[self.common_anchor].date]
+        else:
+            anchor_value = None
+
+        new_data: list[pd.Series[float]] = []
+        for shock_name, ev in self._events.items():
+            shock_dt = pd.to_datetime(ev.date, format="%Y-%m-%d")
+            date_range = pd.bdate_range(
+                start=shock_dt - BDay(ev.days_before),
+                periods=ev.days_before + ev.days_after + 1,
+            )
+            aftermath = selected.reindex(date_range)
+            anchor = (
+                anchor_value
+                if anchor_value is not None
+                else aftermath.loc[ev.date]
+            )
+            # base100: multiplicative index (scale cancels). Otherwise the
+            # subtractive form -- the change since the anchor -- where scale
+            # maps the raw move to the display unit (e.g. x100 for p.b.).
+            if self.base100:
+                aftermath = aftermath / anchor * 100
+            else:
+                aftermath = aftermath - anchor
+            aftermath = aftermath.reset_index(drop=True)
+            aftermath.index = aftermath.index - ev.days_before
+            aftermath.name = shock_name
+            new_data.append(aftermath)
+
+        consolidated = pd.concat(new_data, axis=1)
+        linestyles = ["dotted", "dashed", "dashdot", "solid"]
+
+        font_pt = compact_font_pt(None) if self.compact else None
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **compact_figure_kwargs(self.compact, self.figsize)
+        )
+        ax: Axes = fig.add_subplot()
+
+        # historical shocks in C2 with rotating linestyles; the most recent
+        # (last in dict order) highlighted in C0 solid.
+        for i, col in enumerate(consolidated.columns[:-1]):
+            ax.plot(  # type: ignore[reportUnknownMemberType]
+                consolidated.index,
+                consolidated[col],
+                color="C2",
+                linestyle=linestyles[i % len(linestyles)],
+                label=col,
+            )
+        last_col = consolidated.columns[-1]
+        ax.plot(  # type: ignore[reportUnknownMemberType]
+            consolidated.index,
+            consolidated[last_col],
+            color="C0",
+            label=last_col,
+        )
+
+        ax.axvline(  # type: ignore[reportUnknownMemberType]
+            x=0, color="gray", linestyle="solid", alpha=0.2, label="_nolabel_"
+        )
+        xmin = -max(ev.days_before for ev in self._events.values())
+        xmax = max(ev.days_after for ev in self._events.values())
+        ax.set_xlim(xmin=xmin, xmax=xmax)
+        ax.set_xlabel(  # type: ignore[reportUnknownMemberType]
+            "Días hábiles tras el evento",
+            labelpad=6 if self.compact else 15,
+        )
+
+        style_spines(
+            ax,
+            decimals=self.fmt.decimals,
+            units=self.fmt.units,
+            **AX_CONFIG["spines"],
+        )
+        # base100 anchors at 100; the subtractive form at 0.
+        style_baseline(
+            ax,
+            reference=100 if self.base100 else 0,
+            **AX_CONFIG["baseline"],
+        )
+
+        if self.compact:
+            style_compact_axes(ax, font_pt)
+
+        if self.legend is not None:
+            place_legend(fig, ax, compact=self.compact, ncol=self.legend.ncol)
+
+        return fig, ax
+
+    def save(
+        self,
+        fig: Figure,
+        *,
+        path: Path | None = None,
+        dpi: int | None = None,
+    ) -> Path:
+        """Persist *fig* as a PNG and return the path written.
+
+        Mirrors :meth:`LinePlot.save`: defaults to ``self.out_path``;
+        ``dpi`` overrides the save resolution, derived from the figure
+        size via :func:`dynamic_dpi` when omitted.
+        """
+        target: Path = path if path is not None else self.out_path
+        save_dpi: int = dpi if dpi is not None else dynamic_dpi(fig)
+        fig.savefig(  # type: ignore[reportUnknownMemberType]
+            target, dpi=save_dpi
+        )
+        return target
+
+    def plot(self) -> Axes:
+        """Build the chart and persist it to ``self.out_path``."""
+        fig, ax = self.build()
+        try:
+            self.save(fig)
+        finally:
+            plt.close(fig)
+        return ax

{tesorotools_python-0.0.49 → tesorotools_python-0.0.50}/src/tesorotools/artists/type_curve.py

@@ -120,6 +120,7 @@ class TypeCurve:
         legend: Legend | None = None,
         figsize: tuple[float, float] | None = None,
         points_to_mark: list[str] | None = None,
+        baseline: bool = True,
         compact: bool = False,
         font_pt: float | None = None,
     ) -> None:
@@ -138,6 +139,7 @@ class TypeCurve:
         self.legend = legend
         self.figsize = figsize
         self.points_to_mark = points_to_mark or []
+        self.baseline = baseline
         self.compact = compact
         self.font_pt = font_pt
 
@@ -165,7 +167,11 @@ class TypeCurve:
         ``scale``, ``fmt`` (``!format``), ``legend``
         (``!legend``), ``figsize``, ``points_to_mark``
         (list of ``due_period_code`` to mark on the current
-        line; codes must appear in ``series``), ``compact``
+        line; codes must appear in ``series``), ``baseline``
+        (``True`` -- the default -- draws the 0 line and pins
+        the y-axis to 0, right for a spread curve; ``False``
+        skips it so the y-axis auto-frames an all-positive
+        yield/level curve), ``compact``
         (fixed physical size for two charts per row; thins the
         45-degree tenor labels to the marked points -- or every
         other one -- so they do not collide on the narrow
@@ -284,7 +290,12 @@ class TypeCurve:
             style_compact_axes(ax, font_pt, side="right")
         else:
             _rotate_xticks(ax)
-        style_baseline(ax, 0, **AX_CONFIG["baseline"])
+        # the 0 baseline both draws the zero line and extends the y-limits
+        # down to 0: right for a spread curve (centred on 0), wrong for an
+        # all-positive yield/level curve (it squashes the curve into the top
+        # half). baseline=False skips it so the y-axis auto-frames the data.
+        if self.baseline:
+            style_baseline(ax, 0, **AX_CONFIG["baseline"])
 
         if self.compact:
             legend_ncol = self.legend.ncol if self.legend else None