tesorotools-python 0.1.2__tar.gz → 0.1.4__tar.gz

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tesorotools-python
-Version: 0.1.2
+Version: 0.1.4
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/pyproject.toml

@@ -38,6 +38,7 @@ web = ["streamlit>=1.62", "plotly>=5.24"]
 [project.scripts]
 tesorotools-web = "tesorotools.web.cli:main"
 tesorotools-latex = "tesorotools.latex.cli:main"
+tesorotools-nota = "tesorotools.note.cli:main"
 
 [dependency-groups]
 dev = [

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/src/tesorotools/__init__.py

@@ -66,6 +66,8 @@ from tesorotools.artists import (
     Legend,
     LinePlot,
     MatrixChart,
+    SankeyPlot,
+    ScatterPlot,
     ShockChart,
     StackedAreaPlot,
     StackedBarPlot,
@@ -108,6 +110,8 @@ def _register_builtins() -> None:
     register_artist("shock_plot", ShockChart)
     register_artist("intraday", IntradayPlot)
     register_artist("waterfall", Waterfall)
+    register_artist("sankey", SankeyPlot)
+    register_artist("scatter", ScatterPlot)
 
     register_tag("format", Format)
     register_tag("legend", Legend)
@@ -149,6 +153,8 @@ __all__ = [
     "MatrixChart",
     "RegistryProtocol",
     "Report",
+    "SankeyPlot",
+    "ScatterPlot",
     "Section",
     "ShockChart",
     "StackedAreaPlot",

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/src/tesorotools/artists/__init__.py

@@ -45,6 +45,8 @@ 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.sankey import SankeyPlot
+from tesorotools.artists.scatter import ScatterPlot
 from tesorotools.artists.sharing import share_y_axes
 from tesorotools.artists.shock_plot import ShockChart
 from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
@@ -64,6 +66,8 @@ __all__ = [
     "Legend",
     "LinePlot",
     "MatrixChart",
+    "SankeyPlot",
+    "ScatterPlot",
     "ShockChart",
     "StackedAreaPlot",
     "StackedBarPlot",

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/src/tesorotools/artists/_common.py

@@ -23,11 +23,13 @@ overrides only need to update ``plots.yaml``.
 
 from __future__ import annotations
 
+import math
 from collections.abc import Sequence
 from pathlib import Path
 from typing import Any, Literal, Protocol, Self, cast, runtime_checkable
 
 import matplotlib.pyplot as plt
+import numpy as np
 import pandas as pd
 from matplotlib.axes import Axes
 from matplotlib.dates import (
@@ -152,7 +154,7 @@ def plotly_unsupported(artist: object) -> frozenset[str]:
 
 
 class FigureLifecycle:
-    """``save()`` and ``plot()`` on top of a subclass's ``build()``.
+    """``save()``, ``plot()`` and ``to_tikz()`` on top of ``build()``.
 
     Gives an artist the same three-step life cycle as the rest:
     ``build()`` returns the figure in memory, ``save()`` writes it
@@ -194,6 +196,17 @@ class FigureLifecycle:
             plt.close(fig)
         return ax
 
+    def to_tikz(self, path: Path | None = None) -> Path:
+        """Write the chart as PGF code for LaTeX and return the path.
+
+        By default next to the PNG, with a ``.pgf`` suffix; the document
+        includes it with ``\\input``.  Needs a TeX installation (see
+        :mod:`tesorotools.artists.tikz_backend`).
+        """
+        from tesorotools.artists.tikz_backend import render_tikz
+
+        return render_tikz(self, path)
+
 
 # ----------------------------------------------------------------------
 # Structural contract for image artists
@@ -980,6 +993,40 @@ def apply_date_axis(
             label.set_rotation_mode("anchor")
 
 
+class DecimalsLocator(MaxNLocator):
+    """Matplotlib's default y ticks, kept printable at *decimals*.
+
+    The default locator steps by 1, 2, 2.5 or 5 of a decade, so with a
+    tick format of two decimals it can put ticks every 0.005, and two
+    neighbours print alike (``1,17`` twice).  When the step is not a
+    whole multiple of ``10 ** -decimals`` (the unit) the next of 1, 2 or
+    5 units takes its place: fewer ticks, all different.  Otherwise the
+    ticks are exactly the default ones.
+    """
+
+    def __init__(self, decimals: int, nbins: int | Literal["auto"] = "auto"):
+        super().__init__(  # type: ignore[reportUnknownMemberType]
+            nbins=nbins, steps=[1, 2, 2.5, 5, 10]
+        )
+        self.decimals = decimals
+
+    def tick_values(self, vmin: float, vmax: float) -> Any:
+        ticks = super().tick_values(vmin, vmax)
+        if len(ticks) < 2:
+            return ticks
+        unit = 10.0**-self.decimals
+        step = float(ticks[1] - ticks[0])
+        ratio = step / unit
+        if round(ratio) >= 1 and math.isclose(ratio, round(ratio)):
+            return ticks
+        # The default steps are 1, 2, 2.5 or 5 times a power of ten, so a
+        # step that is no whole multiple of the unit is below 5 units.
+        new = next(f * unit for f in (1, 2, 5) if f * unit >= step)
+        low = math.floor(min(vmin, vmax) / new) * new
+        high = math.ceil(max(vmin, vmax) / new) * new
+        return np.arange(low, high + new / 2, new)
+
+
 def compact_y_axis(ax: Axes) -> None:
     """Denser y-ticks for compact charts (more reference numbers).
 
@@ -994,6 +1041,12 @@ def compact_y_axis(ax: Axes) -> None:
     raw: Any = COMPACT_CONFIG.get("y_max_ticks")
     if raw is None:
         return
+    current = ax.yaxis.get_major_locator()
+    if isinstance(current, DecimalsLocator):
+        ax.yaxis.set_major_locator(
+            DecimalsLocator(current.decimals, nbins=int(raw))
+        )
+        return
     ax.yaxis.set_major_locator(
         MaxNLocator(nbins=int(raw), steps=[1, 2, 2.5, 5, 10])
     )
@@ -1174,6 +1227,7 @@ def place_legend(
     compact: bool,
     ncol: int | None = None,
     position: str = "auto",
+    entries: tuple[list[Any], list[str]] | None = None,
 ) -> MplLegend | None:
     """Place the figure legend, compact-aware, from the labelled artists.
 
@@ -1184,9 +1238,14 @@ def place_legend(
     ``rcParams`` metrics.  ``position`` (``"above"`` / ``"below"`` /
     ``"auto"``) chooses the side through :func:`resolve_legend_position`, so
     a compact chart can carry its legend under the plot instead of over it.
+    ``entries`` passes precomputed ``(handles, labels)`` instead of reading
+    them off *ax* -- for charts whose series span several axes (a
+    ``twinx`` secondary y-axis), in the order the legend should list them.
     Returns ``None`` (drawing nothing) when there are no labels.
     """
-    handles, labels = ax.get_legend_handles_labels()
+    handles, labels = (
+        entries if entries is not None else ax.get_legend_handles_labels()
+    )
     if not labels:
         return None
     side = resolve_legend_position(position, compact=compact)
@@ -1282,6 +1341,7 @@ def style_spines(
         return format_annotation(y, decimals, units)
 
     ax.yaxis.set_major_formatter(FuncFormatter(_fmt_tick))
+    ax.yaxis.set_major_locator(DecimalsLocator(decimals))
     ax.set_xlabel(  # type: ignore[reportUnknownMemberType]
         ""
     )

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/src/tesorotools/artists/bar_line.py

@@ -1,10 +1,14 @@
 """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.
+series as **vertical bars** and others as **marked lines**, by default
+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.  When the scales are too far apart to share an axis (an
+exchange rate around 1.2 against an R^2 between 0 and 1), ``secondary``
+moves any subset of the series, bars or lines, to a right-hand y-axis
+with its own scale, format and title.
 
 Unlike :class:`LinePlot`, the x-axis is **categorical**: one slot per
 observation (``np.arange``) with date-formatted tick labels, so the bars
@@ -38,6 +42,7 @@ from matplotlib.figure import Figure
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     AX_CONFIG,
     Format,
     Legend,
@@ -62,8 +67,8 @@ __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.
+class BarLinePlot(FigureLifecycle):
+    """Combo chart: vertical bars and marked lines, optionally on two axes.
 
     Parameters mirror the other time-series artists where they overlap
     (``out_path``, ``data`` / ``data_path``, ``scale``, ``start_date`` /
@@ -87,6 +92,21 @@ class BarLinePlot:
       ``date_format`` is applied via ``strftime`` (lower-cased, e.g.
       ``"dic-21"``) to a DatetimeIndex; ``max_xticks`` thins the labels
       (``None`` labels every slot).
+    * ``secondary`` -- ids (from ``bars`` and/or ``lines``) drawn against a
+      second y-axis on the right, with its own scale.  Empty (the default)
+      keeps the single shared axis, ticked on the house side (right).  With
+      a secondary axis the primary one moves to the left, its grid is the
+      only one drawn, and the legend still lists every series in declared
+      order (bars, then lines).  It cannot hold every series: the primary
+      axis would be left empty.
+    * ``secondary_fmt`` -- tick format (``!format``) of the secondary axis;
+      defaults to ``fmt``.
+    * ``ylabel`` / ``secondary_ylabel`` -- y-axis titles (empty: none).
+      ``ylabel`` sits on the primary axis' tick side.
+
+    ``baseline`` draws the 0 line on every axis that holds bars (they grow
+    from it) or, with no bars at all, on the primary axis, so a lines-only
+    axis is never stretched down to 0.
     """
 
     #: Keys that change the PNG but never the ``to_plotly()`` figure
@@ -102,6 +122,7 @@ class BarLinePlot:
             "legend.ncol",
             "max_xticks",
             "plot_size",
+            "secondary_fmt.decimals",
             "x_rotation",
         }
     )
@@ -130,6 +151,10 @@ class BarLinePlot:
         max_xticks: int | None = None,
         compact: bool = False,
         font_pt: float | None = None,
+        secondary: list[str] | None = None,
+        secondary_fmt: Format | None = None,
+        ylabel: str = "",
+        secondary_ylabel: str = "",
     ) -> None:
         if out_path.suffix != ".png":
             raise ValueError(f"out_path must be .png: {out_path}")
@@ -139,6 +164,17 @@ class BarLinePlot:
             raise ValueError(
                 "BarLinePlot needs at least one series in `bars` or `lines`"
             )
+        self.secondary = list(secondary or [])
+        unknown = [c for c in self.secondary if c not in self.bars | self.lines]
+        if unknown:
+            raise ValueError(
+                f"`secondary` ids must be in `bars` or `lines`: {unknown}"
+            )
+        if set(self.secondary) >= {*self.bars, *self.lines}:
+            raise ValueError(
+                "`secondary` cannot hold every series: the primary axis "
+                "would be empty"
+            )
         self.out_path = out_path
         self.data = resolve_data(data, data_path)
         self.scale = scale
@@ -157,6 +193,9 @@ class BarLinePlot:
         self.max_xticks = max_xticks
         self.compact = compact
         self.font_pt = font_pt
+        self.secondary_fmt = secondary_fmt or self.fmt
+        self.ylabel = ylabel
+        self.secondary_ylabel = secondary_ylabel
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -179,7 +218,8 @@ class BarLinePlot:
         ``fmt`` (``!format``), ``legend`` (``!legend``), ``figsize``,
         ``plot_size``, ``bar_styles`` / ``line_styles``, ``bar_width``,
         ``date_format``, ``x_rotation``, ``max_xticks``, ``compact``,
-        ``font_pt``.
+        ``font_pt``, ``secondary``, ``secondary_fmt`` (``!format``),
+        ``ylabel`` / ``secondary_ylabel``.
 
         Example
         -------
@@ -194,6 +234,26 @@ class BarLinePlot:
                 surprise: "Sorpresa (pp)"
               fmt: !format {decimals: 0}
               legend: !legend {}
+
+        With scales too far apart for one axis, send some series to the
+        right-hand axis:
+
+        .. code-block:: yaml
+
+            eurusd_fair_value: !bar_line
+              out_path: out/eurusd_fair_value.png
+              data_path: data/eurusd.feather
+              bars:
+                r2: "R^2"
+              lines:
+                eurusd: "EURUSD"
+                fair_value: "Modelo valor justo (60 días)"
+              secondary: [r2]
+              fmt: !format {decimals: 2}
+              secondary_fmt: !format {decimals: 1}
+              ylabel: "EURUSD"
+              secondary_ylabel: "Coeficiente de determinación (R^2)"
+              legend: !legend {}
         """
         cfg: dict[str, Any] = loader.construct_mapping(  # type: ignore[assignment]
             node, deep=True
@@ -287,9 +347,13 @@ class BarLinePlot:
             **compact_figure_kwargs(self.compact, self.figsize)
         )
         ax: Axes = fig.add_subplot()
+        ax2: Axes | None = ax.twinx() if self.secondary else None
+
+        def target(col: str) -> Axes:
+            return ax2 if ax2 is not None and col in self.secondary else ax
 
         # Bars first (behind the lines). Several bar series share each slot,
-        # dodged side by side; a single series is centred.
+        # dodged side by side (across both axes); a single one 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))
@@ -299,7 +363,7 @@ class BarLinePlot:
             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]
+            target(col).bar(  # type: ignore[reportUnknownMemberType]
                 x + offset,
                 values,
                 width=each,
@@ -317,7 +381,7 @@ class BarLinePlot:
             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]
+            target(col).plot(  # type: ignore[reportUnknownMemberType]
                 x,
                 plot_data[col].to_numpy(dtype=np.float64),
                 label=label,
@@ -336,14 +400,31 @@ class BarLinePlot:
         # 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"])
-
+            on_primary, on_secondary = self._baseline_on()
+            for axis, on in ((ax, on_primary), (ax2, on_secondary)):
+                if on and axis is not None:
+                    style_baseline(axis, 0, **AX_CONFIG["baseline"])
+
+        side = "right"
+        if ax2 is not None:
+            side = "left"
+            ax.yaxis.tick_left()
+            self._style_secondary(ax, ax2, font_pt)
         if self.compact:
-            style_compact_axes(ax, font_pt, side="right")
+            style_compact_axes(ax, font_pt, side=side)
+        if self.ylabel:
+            ax.yaxis.set_label_position(side)  # type: ignore[reportArgumentType]
+            ax.set_ylabel(  # type: ignore[reportUnknownMemberType]
+                self.ylabel, fontsize=font_pt
+            )
 
         if self.legend is not None:
             place_legend(
-                fig, ax, compact=self.compact, **legend_layout(self.legend)
+                fig,
+                ax,
+                compact=self.compact,
+                entries=self._legend_entries(ax, ax2),
+                **legend_layout(self.legend),
             )
 
         if self.plot_size is not None and not self.compact:
@@ -351,6 +432,58 @@ class BarLinePlot:
 
         return fig, ax
 
+    def _baseline_on(self) -> tuple[bool, bool]:
+        """``(primary, secondary)``: the axes that get the 0 line.
+
+        Those holding bars (they grow from 0) or, with no bars at all, the
+        primary one.  Shared by :meth:`build` and :meth:`to_plotly`.
+        """
+        on_secondary = [c in self.secondary for c in self.bars]
+        secondary = any(on_secondary)
+        primary = not all(on_secondary) or not secondary
+        return primary, secondary
+
+    def _style_secondary(
+        self, ax: Axes, ax2: Axes, font_pt: float | None
+    ) -> None:
+        """Style the right-hand axis: own format, no grid, title, z-order.
+
+        The twin is drawn above the primary by default, which would hide
+        the primary series behind secondary bars; when the secondary holds
+        bars the primary is brought forward with a transparent background.
+        """
+        style_spines(
+            ax2,
+            decimals=self.secondary_fmt.decimals,
+            units=self.secondary_fmt.units,
+            **AX_CONFIG["spines"],
+        )
+        ax2.grid(False)  # type: ignore[reportUnknownMemberType]
+        if self.compact:
+            style_compact_axes(ax2, font_pt, side="right")
+        if self.secondary_ylabel:
+            ax2.set_ylabel(  # type: ignore[reportUnknownMemberType]
+                self.secondary_ylabel, fontsize=font_pt
+            )
+        if any(c in self.secondary for c in self.bars):
+            ax.set_zorder(ax2.get_zorder() + 1)
+            ax.patch.set_visible(False)
+
+    def _legend_entries(
+        self, ax: Axes, ax2: Axes | None
+    ) -> tuple[list[Any], list[str]]:
+        """Handles and labels of both axes, in declared order."""
+        handles, labels = ax.get_legend_handles_labels()
+        if ax2 is not None:
+            more_handles, more_labels = ax2.get_legend_handles_labels()
+            handles, labels = handles + more_handles, labels + more_labels
+        order = [*self.bars.values(), *self.lines.values()]
+        pairs = sorted(
+            zip(handles, labels, strict=True),
+            key=lambda pair: order.index(pair[1]),
+        )
+        return [h for h, _ in pairs], [label for _, label in pairs]
+
     def save(
         self,
         fig: Figure,

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/src/tesorotools/artists/box_plot.py

@@ -44,6 +44,7 @@ from matplotlib.patches import Patch
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     AX_CONFIG,
     Format,
     Legend,
@@ -105,7 +106,7 @@ def _weighted_quantile(
     return float(np.interp(q, cum, v))
 
 
-class BoxPlot:
+class BoxPlot(FigureLifecycle):
     """Box-and-whisker chart, one box per category.
 
     Parameters mirror the other artists where they overlap (``out_path``,

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/src/tesorotools/artists/intraday_plot.py

@@ -42,6 +42,7 @@ from matplotlib.figure import Figure
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    FigureLifecycle,
     AX_CONFIG,
     Format,
     Legend,
@@ -66,7 +67,7 @@ __all__ = ["IntradayPlot"]
 _MAX_XTICKS = 10
 
 
-class IntradayPlot:
+class IntradayPlot(FigureLifecycle):
     """Single-instrument intraday line chart on a gap-free ordinal axis.
 
     Parameters mirror the other image artists where they overlap

{tesorotools_python-0.1.2 → tesorotools_python-0.1.4}/src/tesorotools/artists/line_plot.py

@@ -23,6 +23,8 @@ from matplotlib.ticker import FuncFormatter
 from yaml.nodes import MappingNode
 
 from tesorotools.artists._common import (
+    DecimalsLocator,
+    FigureLifecycle,
     AX_CONFIG,
     DATE_DENSITY_LEVELS,
     Format,
@@ -56,7 +58,7 @@ locale.setlocale(locale.LC_ALL, "")
 __all__ = ["LinePlot"]
 
 
-class LinePlot:
+class LinePlot(FigureLifecycle):
     """Time-series line chart with the tesorotools visual style.
 
     Parameters mirror the other image artists where they
@@ -542,6 +544,7 @@ class LinePlot:
                 return format_annotation(y, axis_decimals, units)
 
             ax.yaxis.set_major_formatter(FuncFormatter(_fmt_axis_tick))
+            ax.yaxis.set_major_locator(DecimalsLocator(axis_decimals))
         if self.baseline:
             reference = 100 if self.base_100 else 0
             style_baseline(ax, reference, **AX_CONFIG["baseline"])