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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.49
+Version: 0.0.51
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10
@@ -19,5 +19,7 @@ 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: interactive-plots
+Requires-Dist: plotly>=5.0; extra == 'interactive-plots'
 Provides-Extra: lseg
 Requires-Dist: lseg-data>=2.1; extra == 'lseg'

{tesorotools_python-0.0.49 → tesorotools_python-0.0.51}/pyproject.toml

@@ -29,6 +29,7 @@ bde = ["requests>=2.31"]
 ecb = ["requests>=2.31"]
 imf = ["requests>=2.31", "truststore>=0.10"]
 lseg = ["lseg-data>=2.1"]
+interactive_plots = ["plotly>=5.0"]
 
 [dependency-groups]
 dev = [
@@ -37,6 +38,9 @@ dev = [
     "pre-commit>=4.0",
     "pandas-stubs>=2.2",
     "coverage>=7.0",
+    # the interactive Plotly backend is an optional extra, but the test
+    # suite exercises it (and the 100% coverage gate requires it present).
+    "plotly>=5.0",
 ]
 
 [build-system]

{tesorotools_python-0.0.49 → tesorotools_python-0.0.51}/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
@@ -44,12 +53,16 @@ from tesorotools._registry import (
     register_tags,
 )
 from tesorotools.artists import (
+    BarLinePlot,
+    BoxPlot,
     Format,
     GroupedBarChart,
     HorizontalBarChart,
+    IntradayPlot,
     Legend,
     LinePlot,
     MatrixChart,
+    ShockChart,
     StackedAreaPlot,
     StackedBarPlot,
     TypeCurve,
@@ -78,6 +91,8 @@ from tesorotools.render import (
 
 def _register_builtins() -> None:
     register_artist("line_plot", LinePlot)
+    register_artist("bar_line", BarLinePlot)
+    register_artist("box_plot", BoxPlot)
     register_artist("stacked_area", StackedAreaPlot)
     register_artist("stacked_bar", StackedBarPlot)
     register_artist("barh", HorizontalBarChart)
@@ -85,6 +100,8 @@ 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("intraday", IntradayPlot)
     register_artist("waterfall", Waterfall)
 
     register_tag("format", Format)
@@ -103,7 +120,10 @@ _register_builtins()
 
 
 __all__ = [
+    "__version__",
     "Artist",
+    "BarLinePlot",
+    "BoxPlot",
     "BdeProvider",
     "BuildContext",
     "CompositeRegistry",
@@ -115,6 +135,7 @@ __all__ = [
     "HorizontalBarChart",
     "Image",
     "Images",
+    "IntradayPlot",
     "Legend",
     "LinePlot",
     "LSEGProvider",
@@ -122,6 +143,7 @@ __all__ = [
     "RegistryProtocol",
     "Report",
     "Section",
+    "ShockChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "Subtitle",

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

@@ -26,9 +26,13 @@ strictly image output.
 """
 
 from tesorotools.artists._common import Artist, Format, Legend
+from tesorotools.artists.bar_line import BarLinePlot
 from tesorotools.artists.barh_plot import GroupedBarChart, HorizontalBarChart
+from tesorotools.artists.box_plot import BoxPlot
+from tesorotools.artists.intraday_plot import IntradayPlot
 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
@@ -36,12 +40,16 @@ from tesorotools.artists.waterfall import Waterfall
 
 __all__ = [
     "Artist",
+    "BarLinePlot",
+    "BoxPlot",
     "Format",
     "GroupedBarChart",
     "HorizontalBarChart",
+    "IntradayPlot",
     "Legend",
     "LinePlot",
     "MatrixChart",
+    "ShockChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "TypeCurve",

{tesorotools_python-0.0.49 → tesorotools_python-0.0.51}/src/tesorotools/artists/_common.py

@@ -96,9 +96,7 @@ def dynamic_dpi(fig: Figure) -> int:
 class Artist(Protocol):
     """Structural contract every image artist satisfies.
 
-    The five built-in artists (``LinePlot``,
-    ``StackedAreaPlot``, ``StackedBarPlot``, ``TypeCurve``,
-    ``HorizontalBarChart``) and any third-party artist
+    The built-in artists and any third-party artist
     registered via :func:`tesorotools.register_artist`
     expose the same three-piece surface:
 

tesorotools_python-0.0.51/src/tesorotools/artists/bar_line.py

@@ -0,0 +1,362 @@
+"""Bar + line combo chart artist, registered as ``!bar_line``.
+
+Defines :class:`BarLinePlot`: one time-series chart that draws some
+series as **vertical bars** and others as **marked lines** on a single
+shared y-axis.  The canonical use is a secondary magnitude in bars (an
+earnings *surprise* in p.p.) under a primary series as the highlighted
+line (earnings *growth* in %), both read against the same 0 baseline.
+
+Unlike :class:`LinePlot`, the x-axis is **categorical**: one slot per
+observation (``np.arange``) with date-formatted tick labels, so the bars
+sit at even spacing regardless of the calendar gaps between periods --
+the layout every quarterly/monthly bar chart wants.  Lines are drawn at
+the same integer positions so they overlay the bars exactly.
+
+This is deliberately *not* an extension of :class:`StackedBarPlot`'s
+``overlay_series`` (a hardcoded black 1.5 px line, no markers): here the
+line is a first-class, fully styleable series -- colour, marker,
+linewidth -- and the bars are the secondary layer.
+
+Layout and the shared ``Format`` / ``Legend`` config holders live in
+:mod:`tesorotools.artists._common`; combo styling defaults come from
+``PLOT_CONFIG['bar_line']``.  Render lifecycle mirrors
+:class:`LinePlot`: ``build()`` returns ``(Figure, Axes)`` in memory;
+``save(fig)`` persists to ``out_path``; ``plot()`` does both.
+"""
+
+from __future__ import annotations
+
+import locale
+from pathlib import Path
+from typing import Any, Self
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from yaml.nodes import MappingNode
+
+from tesorotools.artists._common import (
+    AX_CONFIG,
+    Format,
+    Legend,
+    adjust_figure_for_plot_size,
+    compact_figure_kwargs,
+    compact_font_pt,
+    dynamic_dpi,
+    place_legend,
+    resolve_data,
+    style_baseline,
+    style_compact_axes,
+    style_spines,
+)
+from tesorotools.utils.matplotlib import PLOT_CONFIG
+from tesorotools.utils.template import TemplateLoader
+
+locale.setlocale(locale.LC_ALL, "")
+
+__all__ = ["BarLinePlot"]
+
+BAR_LINE_CONFIG: dict[str, Any] = PLOT_CONFIG["bar_line"]
+
+
+class BarLinePlot:
+    """Combo chart: vertical bars and marked lines on one shared axis.
+
+    Parameters mirror the other time-series artists where they overlap
+    (``out_path``, ``data`` / ``data_path``, ``scale``, ``start_date`` /
+    ``end_date``, ``fmt``, ``legend``, ``figsize``, ``plot_size``,
+    ``compact`` / ``font_pt``).  Combo-specific knobs:
+
+    * ``bars`` -- ``id -> label`` mapping drawn as vertical bars.  Several
+      bar series are grouped (dodged) side by side within each slot.
+    * ``lines`` -- ``id -> label`` mapping drawn as marked lines, on top of
+      the bars.  At least one of ``bars`` / ``lines`` must be non-empty.
+    * ``bar_styles`` / ``line_styles`` -- per-series matplotlib kwargs.
+      Lines default to a round marker (``marker: "o"``, configurable per
+      series) and the combo linewidth from ``plots.yaml``; bars default to
+      that section's alpha.  Colours default to the house cycle -- lines
+      first (``C0``, ``C2``, ...), bars after them -- so the common one
+      line + one bar case lands on ``C0`` (line) over ``C1`` (bar).
+    * ``bar_width`` -- total width of each slot's bar group (fraction of the
+      unit spacing).
+    * ``baseline`` -- draw the 0 line (default ``True``; bars grow from it).
+    * ``date_format`` / ``x_rotation`` / ``max_xticks`` -- x tick labelling.
+      ``date_format`` is applied via ``strftime`` (lower-cased, e.g.
+      ``"dic-21"``) to a DatetimeIndex; ``max_xticks`` thins the labels
+      (``None`` labels every slot).
+    """
+
+    def __init__(
+        self,
+        out_path: Path,
+        *,
+        data: pd.DataFrame | None = None,
+        data_path: Path | None = None,
+        bars: dict[str, str] | None = None,
+        lines: dict[str, str] | None = None,
+        scale: float = 1,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        baseline: bool = True,
+        fmt: Format | None = None,
+        legend: Legend | None = None,
+        figsize: tuple[float, float] | None = None,
+        plot_size: tuple[float, float] | None = None,
+        bar_styles: dict[str, dict[str, Any]] | None = None,
+        line_styles: dict[str, dict[str, Any]] | None = None,
+        bar_width: float = 0.7,
+        date_format: str = "%b-%y",
+        x_rotation: float = 45,
+        max_xticks: int | None = None,
+        compact: bool = False,
+        font_pt: float | None = None,
+    ) -> None:
+        if out_path.suffix != ".png":
+            raise ValueError(f"out_path must be .png: {out_path}")
+        self.bars = bars or {}
+        self.lines = lines or {}
+        if not self.bars and not self.lines:
+            raise ValueError(
+                "BarLinePlot needs at least one series in `bars` or `lines`"
+            )
+        self.out_path = out_path
+        self.data = resolve_data(data, data_path)
+        self.scale = scale
+        self.start_date = start_date
+        self.end_date = end_date
+        self.baseline = baseline
+        self.fmt = fmt or Format()
+        self.legend = legend
+        self.figsize = figsize
+        self.plot_size = plot_size
+        self.bar_styles = bar_styles or {}
+        self.line_styles = line_styles or {}
+        self.bar_width = bar_width
+        self.date_format = date_format
+        self.x_rotation = x_rotation
+        self.max_xticks = max_xticks
+        self.compact = compact
+        self.font_pt = font_pt
+
+    @classmethod
+    def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
+        """Build a :class:`BarLinePlot` from the ``!bar_line`` YAML tag.
+
+        Required keys
+        -------------
+        ``out_path``
+            ``.png`` destination path.
+        ``data_path``
+            ``.feather`` file with the time-series DataFrame
+            (DatetimeIndex × series columns).
+        ``bars`` and/or ``lines``
+            ``id -> display_label`` mappings; at least one must be
+            non-empty and every id must be a column of the DataFrame.
+
+        Optional keys (forwarded as-is to ``__init__``)
+        ----------------------------------------------
+        ``scale``, ``start_date`` / ``end_date``, ``baseline``,
+        ``fmt`` (``!format``), ``legend`` (``!legend``), ``figsize``,
+        ``plot_size``, ``bar_styles`` / ``line_styles``, ``bar_width``,
+        ``date_format``, ``x_rotation``, ``max_xticks``, ``compact``,
+        ``font_pt``.
+
+        Example
+        -------
+        .. code-block:: yaml
+
+            stoxx_earnings: !bar_line
+              out_path: out/stoxx_earnings.png
+              data_path: data/earnings.feather
+              lines:
+                growth: "Crecimiento beneficios (%)"
+              bars:
+                surprise: "Sorpresa (pp)"
+              fmt: !format {decimals: 0}
+              legend: !legend {}
+        """
+        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 _prepare_data(self) -> pd.DataFrame:
+        """Slice by date and scale -- the backend-neutral IR.
+
+        Returns the sliced, scaled frame carrying every bar and line
+        column in dict order.  NaNs are preserved (lines skip missing
+        points, bars zero them at draw time), so the transform is shared
+        byte-for-byte by :meth:`build` and :meth:`to_plotly`.
+        """
+        start = (
+            pd.Timestamp(self.start_date)
+            if self.start_date
+            else self.data.index.min()
+        )
+        end = (
+            pd.Timestamp(self.end_date)
+            if self.end_date
+            else self.data.index.max()
+        )
+        cols = list(self.bars.keys()) + list(self.lines.keys())
+        plot_data = self.data.loc[start:end, cols]
+        plot_data = plot_data.dropna(how="all")
+        return plot_data * self.scale
+
+    def _check_columns(self) -> None:
+        missing = [
+            c for c in (*self.bars, *self.lines) if c not in self.data.columns
+        ]
+        if missing:
+            raise KeyError(
+                f"BarLinePlot columns not found in data: {missing}. "
+                f"Available: {list(self.data.columns)}"
+            )
+
+    def _fmt_date(self, value: Any) -> str:
+        """Format one x label: ``strftime`` (lower-cased) or ``str``."""
+        strftime = getattr(value, "strftime", None)
+        if strftime is None:
+            return str(value)
+        return strftime(self.date_format).lower().rstrip(".")
+
+    def _format_xticks(
+        self,
+        ax: Axes,
+        index: pd.Index,
+        x: np.ndarray[tuple[int], np.dtype[np.intp]],
+    ) -> None:
+        """Place date-formatted x ticks, thinned to ``max_xticks``."""
+        n = len(index)
+        divisor = self.max_xticks or (6 if self.compact else n)
+        step = max(1, -(-n // max(1, divisor)))  # ceil(n / divisor)
+        positions = list(range(0, n, step))
+        labels = [self._fmt_date(index[i]) for i in positions]
+        ax.set_xticks(  # type: ignore[reportUnknownMemberType]
+            positions
+        )
+        ax.set_xticklabels(  # type: ignore[reportUnknownMemberType]
+            labels,
+            rotation=self.x_rotation,
+            ha="right" if self.x_rotation else "center",
+        )
+
+    def to_plotly(self) -> Any:
+        """Render the same combo chart as an interactive Plotly figure.
+
+        Experimental sibling of :meth:`build`; requires the optional
+        ``interactive_plots`` extra (``plotly``), imported lazily.
+        """
+        from tesorotools.artists.plotly_backend import bar_line_to_figure
+
+        return bar_line_to_figure(self)
+
+    def build(self) -> tuple[Figure, Axes]:
+        """Render the chart in memory; return ``(fig, ax)`` without saving."""
+        self._check_columns()
+        plot_data = self._prepare_data()
+        x = np.arange(len(plot_data))
+        cycle: list[str] = plt.rcParams["axes.prop_cycle"].by_key()["color"]
+
+        font_pt = compact_font_pt(self.font_pt) if self.compact else None
+        fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
+            **compact_figure_kwargs(self.compact, self.figsize)
+        )
+        ax: Axes = fig.add_subplot()
+
+        # Bars first (behind the lines). Several bar series share each slot,
+        # dodged side by side; a single series is centred.
+        n_bars = len(self.bars)
+        each = self.bar_width / n_bars if n_bars else self.bar_width
+        default_alpha: float = float(BAR_LINE_CONFIG["bar"].get("alpha", 0.9))
+        for j, (col, label) in enumerate(self.bars.items()):
+            style = dict(self.bar_styles.get(col, {}))
+            style.setdefault("color", cycle[(len(self.lines) + j) % len(cycle)])
+            style.setdefault("alpha", default_alpha)
+            offset = (j - (n_bars - 1) / 2) * each
+            values = plot_data[col].fillna(0).to_numpy(dtype=np.float64)
+            ax.bar(  # type: ignore[reportUnknownMemberType]
+                x + offset,
+                values,
+                width=each,
+                label=label,
+                zorder=2,
+                **style,
+            )
+
+        # Lines on top, marked. Defaults (marker, linewidth, markersize) come
+        # from the bar_line config; per-series line_styles override them.
+        line_cfg: dict[str, Any] = BAR_LINE_CONFIG["line"]
+        for i, (col, label) in enumerate(self.lines.items()):
+            style = dict(self.line_styles.get(col, {}))
+            style.setdefault("color", cycle[i % len(cycle)])
+            style.setdefault("marker", line_cfg.get("marker", "o"))
+            style.setdefault("linewidth", line_cfg.get("linewidth", 2))
+            style.setdefault("markersize", line_cfg.get("markersize", 5))
+            ax.plot(  # type: ignore[reportUnknownMemberType]
+                x,
+                plot_data[col].to_numpy(dtype=np.float64),
+                label=label,
+                zorder=3,
+                **style,
+            )
+
+        self._format_xticks(ax, plot_data.index, x)
+
+        style_spines(
+            ax,
+            decimals=self.fmt.decimals,
+            units=self.fmt.units,
+            **AX_CONFIG["spines"],
+        )
+        # style_spines enables the y grid only (axis="y"), which is what these
+        # charts read against; the categorical x-axis stays gridless.
+        if self.baseline:
+            style_baseline(ax, 0, **AX_CONFIG["baseline"])
+
+        if self.compact:
+            style_compact_axes(ax, font_pt, side="right")
+
+        legend_ncol = self.legend.ncol if self.legend else None
+        if self.legend is not None:
+            place_legend(fig, ax, compact=self.compact, ncol=legend_ncol)
+
+        if self.plot_size is not None and not self.compact:
+            adjust_figure_for_plot_size(fig, ax, self.plot_size)
+
+        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.51}/src/tesorotools/artists/barh_plot.py

@@ -604,6 +604,16 @@ class HorizontalBarChart:
             cfg["data_path"] = Path(cfg["data_path"])
         return cls(**cfg)
 
+    def to_plotly(self) -> Any:
+        """Render the same horizontal bars as an interactive Plotly figure.
+
+        Experimental sibling of :meth:`plot`; requires the optional
+        ``interactive_plots`` extra (``plotly``), imported lazily.
+        """
+        from tesorotools.artists.plotly_backend import horizontal_bar_to_figure
+
+        return horizontal_bar_to_figure(self)
+
     def _build_frame(self) -> pd.DataFrame:
         """Stage the per-bar value/colour/alpha DataFrame."""
         ids = list(self.alias.keys())
@@ -846,6 +856,16 @@ class GroupedBarChart:
             cfg["data_path"] = Path(cfg["data_path"])
         return cls(**cfg)
 
+    def to_plotly(self) -> Any:
+        """Render the same grouped bars as an interactive Plotly figure.
+
+        Experimental sibling of :meth:`plot`; requires the optional
+        ``interactive_plots`` extra (``plotly``), imported lazily.
+        """
+        from tesorotools.artists.plotly_backend import grouped_bar_to_figure
+
+        return grouped_bar_to_figure(self)
+
     def plot(self) -> Axes:
         """Render the chart and persist it to ``self.out_path``."""
         cat_ids = list(self.categories.keys())