tesorotools-python 0.1.1__tar.gz → 0.1.3__tar.gz

{tesorotools_python-0.1.1 → tesorotools_python-0.1.3}/PKG-INFO

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

{tesorotools_python-0.1.1 → tesorotools_python-0.1.3}/src/tesorotools/__init__.py

@@ -72,6 +72,7 @@ from tesorotools.artists import (
     TypeCurve,
     VectorPlot,
     Waterfall,
+    share_y_axes,
 )
 from tesorotools.orchestration import CompositeRegistry, iter_contexts
 from tesorotools.providers.base import (
@@ -177,6 +178,7 @@ __all__ = [
     "register_providers",
     "register_tag",
     "register_tags",
+    "share_y_axes",
 ]
 
 

{tesorotools_python-0.1.1 → tesorotools_python-0.1.3}/src/tesorotools/artists/__init__.py

@@ -20,6 +20,9 @@ Each class follows the same shape:
   Plotly figure (all but ``IntradayPlot``);
   :func:`plotly_unsupported` lists the keys it drops.
 
+:func:`share_y_axes` gives the charts that declare the same
+``y_group`` one common y scale.
+
 Shared layout, annotation and styling helpers (plus the
 ``Format`` and ``Legend`` config holders) live in
 :mod:`tesorotools.artists._common`.
@@ -42,6 +45,7 @@ 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.sharing import share_y_axes
 from tesorotools.artists.shock_plot import ShockChart
 from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
 from tesorotools.artists.type_curve import TypeCurve
@@ -67,4 +71,5 @@ __all__ = [
     "VectorPlot",
     "Waterfall",
     "plotly_unsupported",
+    "share_y_axes",
 ]

{tesorotools_python-0.1.1 → tesorotools_python-0.1.3}/src/tesorotools/artists/_common.py

@@ -23,6 +23,7 @@ overrides only need to update ``plots.yaml``.
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Any, Literal, Protocol, Self, cast, runtime_checkable
 
@@ -1173,6 +1174,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.
 
@@ -1183,9 +1185,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)
@@ -1299,6 +1306,26 @@ def style_spines(
     )
 
 
+def check_y_limits(
+    limits: Sequence[float] | None,
+) -> tuple[float, float] | None:
+    """Validate a ``y_limits`` pair and return it as ``(bottom, top)``.
+
+    YAML hands the pair over as a list, so any two-item sequence is
+    accepted; ``None`` (no fixed range) passes through.  Raises
+    ``ValueError`` unless there are exactly two numbers with
+    ``bottom < top``.
+    """
+    if limits is None:
+        return None
+    if len(limits) != 2:
+        raise ValueError(f"y_limits must be (bottom, top): {limits!r}")
+    bottom, top = float(limits[0]), float(limits[1])
+    if not bottom < top:
+        raise ValueError(f"y_limits bottom must be below top: {limits!r}")
+    return bottom, top
+
+
 def style_baseline(
     ax: Axes,
     reference: float = 0,
@@ -1339,6 +1366,7 @@ def annotate_last_values(
     fontsize: float | None = None,
     right_pad_px: float = 10.0,
     headroom_pad_pt: float = 0.0,
+    grow_top: bool = True,
 ) -> None:
     """Label the last non-NaN value of each column on the right.
 
@@ -1365,7 +1393,8 @@ def annotate_last_values(
     y-limit, that limit grows enough to keep this many points
     free and the labels are re-packed at the new scale, so a
     tall stack never spills into a legend above the axes (nor
-    is clipped at the top).
+    is clipped at the top).  ``grow_top=False`` keeps the top
+    y-limit as it is (a fixed or shared y range must not move).
     """
     fig = ax.get_figure()
     if fig is None:
@@ -1437,7 +1466,7 @@ def annotate_last_values(
     pad_px = headroom_pad_pt * fig.dpi / 72.0
     top_axes_px: float = trans.transform((0, ymax))[1]  # type: ignore[reportUnknownArgumentType]
     needed_px = placements[-1] + text_height / 2 + pad_px
-    if needed_px > top_axes_px:
+    if grow_top and needed_px > top_axes_px:
         new_top: float = trans.inverted().transform(  # type: ignore[reportUnknownArgumentType]
             (0, needed_px)
         )[1]

{tesorotools_python-0.1.1 → tesorotools_python-0.1.3}/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
@@ -63,7 +67,7 @@ BAR_LINE_CONFIG: dict[str, Any] = PLOT_CONFIG["bar_line"]
 
 
 class BarLinePlot:
-    """Combo chart: vertical bars and marked lines on one shared axis.
+    """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 +91,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 +121,7 @@ class BarLinePlot:
             "legend.ncol",
             "max_xticks",
             "plot_size",
+            "secondary_fmt.decimals",
             "x_rotation",
         }
     )
@@ -130,6 +150,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 +163,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 +192,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 +217,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 +233,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 +346,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 +362,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 +380,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 +399,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 +431,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.1 → tesorotools_python-0.1.3}/src/tesorotools/artists/line_plot.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import datetime
 import locale
+from collections.abc import Sequence
 from pathlib import Path
 from typing import Any, ClassVar, Self
 
@@ -30,6 +31,7 @@ from tesorotools.artists._common import (
     adjust_figure_for_plot_size,
     annotate_last_values,
     apply_date_axis,
+    check_y_limits,
     compact_date_axis,
     compact_figure_kwargs,
     compact_font_pt,
@@ -160,6 +162,15 @@ class LinePlot:
       **height** (keeping the width) so the plot area is not
       squashed by a large legend or rotated date labels. Skipped
       when ``plot_size`` is set (that already fixes the axes size).
+    * ``y_limits`` -- fix the y-axis to ``(bottom, top)`` on both
+      backends. The range is strict: the baseline, the reference
+      lines and the end-of-series labels no longer widen it.
+    * ``y_group`` -- name of a group of charts that must share the
+      same y scale (e.g. US and European equities, both base 100,
+      in two separate charts). It does nothing on its own:
+      :func:`tesorotools.artists.share_y_axes` measures every chart
+      of each group and sets the union of their ranges as their
+      ``y_limits``. Mutually exclusive with ``y_limits``.
 
     Render lifecycle: ``build()`` returns ``(Figure, Axes)``
     in memory; ``save(fig)`` persists to ``out_path``;
@@ -223,9 +234,16 @@ class LinePlot:
         ref_lines: list[dict[str, Any]] | None = None,
         show_means: bool = False,
         means_window: tuple[Any, Any] | None = None,
+        y_limits: Sequence[float] | None = None,
+        y_group: str | None = None,
     ) -> None:
         if out_path.suffix != ".png":
             raise ValueError(f"out_path must be .png: {out_path}")
+        if y_limits is not None and y_group is not None:
+            raise ValueError(
+                "y_limits and y_group are mutually exclusive: a group "
+                "computes its shared y_limits (see share_y_axes)"
+            )
         if base_100 and base_0:
             raise ValueError(
                 "base_100 and base_0 are mutually exclusive: a series is "
@@ -269,6 +287,8 @@ class LinePlot:
         self.ref_lines = ref_lines or []
         self.show_means = show_means
         self.means_window = means_window
+        self.y_limits = check_y_limits(y_limits)
+        self.y_group = y_group
 
     @property
     def _pin_start_date(self) -> bool:
@@ -324,7 +344,8 @@ class LinePlot:
         ``axis_decimals``, ``axis_units``, ``annotate_units``,
         ``date_density``, ``date_rotation``, ``date_show_start``,
         ``adapt_height``,
-        ``ref_lines``, ``show_means``, ``means_window``.
+        ``ref_lines``, ``show_means``, ``means_window``,
+        ``y_limits``, ``y_group``.
 
         Example
         -------
@@ -462,6 +483,11 @@ class LinePlot:
             # data point. annotate_last_values reopens room on the right.
             ax.margins(x=0)
 
+        # a fixed (or group-shared) y range goes in BEFORE the annotations:
+        # they pack their labels at the final scale.
+        if self.y_limits is not None:
+            ax.set_ylim(*self.y_limits)
+
         if self.vlines:
             draw_vlines(ax, self.vlines)
 
@@ -494,6 +520,7 @@ class LinePlot:
                 headroom_pad_pt=(
                     compact_headroom_pad_pt() if self.compact else 0.0
                 ),
+                grow_top=self.y_limits is None,
             )
 
         style_spines(
@@ -536,6 +563,10 @@ class LinePlot:
             )
             lo, hi = ax.get_ylim()
             ax.set_ylim(min(ref_line["y"], lo), max(ref_line["y"], hi))
+        if self.y_limits is not None:
+            # the baseline and the reference lines widen the range to show
+            # themselves; a fixed range wins over them.
+            ax.set_ylim(*self.y_limits)
 
         # per-series historical mean as a dotted same-colour line (the old
         # `medias=True`): the mean is taken over means_window (or the whole

{tesorotools_python-0.1.1 → tesorotools_python-0.1.3}/src/tesorotools/artists/plotly_backend.py

@@ -197,10 +197,11 @@ def _legend_side(fig: go.Figure, legend: Legend | None) -> None:
     )
 
 
-def _baseline(fig: go.Figure, reference: float) -> None:
-    """Draw the house baseline (axhline) at *reference*."""
+def _baseline(fig: go.Figure, reference: float, *, yref: str = "y") -> None:
+    """Draw the house baseline (axhline) at *reference* on axis *yref*."""
     fig.add_hline(
         y=reference,
+        yref=yref,
         line_color=AX_CONFIG["baseline"]["color"],
         line_width=AX_CONFIG["baseline"]["linewidth"],
     )
@@ -302,6 +303,9 @@ def line_plot_to_figure(chart: LinePlot) -> go.Figure:
     # toggles (mirrors the matplotlib artist).
     if chart.fmt.units and chart.axis_units:
         fig.update_yaxes(ticksuffix=chart.fmt.units)
+    # fixed or group-shared y range (see share_y_axes)
+    if chart.y_limits is not None:
+        fig.update_yaxes(range=list(chart.y_limits))
     _legend_side(fig, chart.legend)
     return fig
 
@@ -500,7 +504,8 @@ def bar_line_to_figure(chart: BarLinePlot) -> go.Figure:
     """Interactive ``Figure`` from a :class:`BarLinePlot`.
 
     Bars (grouped) and marked lines share one y-axis over a categorical
-    x-axis of the same date-formatted labels the matplotlib artist uses.
+    x-axis of the same date-formatted labels the matplotlib artist uses;
+    the ``secondary`` series go to an overlaid right-hand ``yaxis2``.
     """
     plot_data = chart._prepare_data()
     palette = _house_palette()
@@ -512,6 +517,9 @@ def bar_line_to_figure(chart: BarLinePlot) -> go.Figure:
     default_alpha = float(BAR_LINE_CONFIG["bar"].get("alpha", 0.9))
     line_cfg = BAR_LINE_CONFIG["line"]
 
+    def yaxis(col: str) -> str:
+        return "y2" if col in chart.secondary else "y"
+
     for j, (col, label) in enumerate(chart.bars.items()):
         style = chart.bar_styles.get(col, {})
         color = (
@@ -522,6 +530,7 @@ def bar_line_to_figure(chart: BarLinePlot) -> go.Figure:
                 x=x,
                 y=plot_data[col].fillna(0),
                 name=label,
+                yaxis=yaxis(col),
                 marker_color=_color(color, style.get("alpha", default_alpha)),
             )
         )
@@ -538,6 +547,7 @@ def bar_line_to_figure(chart: BarLinePlot) -> go.Figure:
                 y=plot_data[col],
                 mode="lines+markers",
                 name=label,
+                yaxis=yaxis(col),
                 line={
                     "color": _color(color),
                     "width": style.get(
@@ -549,10 +559,27 @@ def bar_line_to_figure(chart: BarLinePlot) -> go.Figure:
         )
 
     fig.update_layout(barmode="group")
+    if chart.ylabel:
+        fig.update_layout(yaxis_title_text=chart.ylabel)
+    if chart.secondary:
+        fig.update_layout(
+            yaxis_side="left",
+            yaxis2={
+                "overlaying": "y",
+                "side": "right",
+                "showgrid": False,
+                "ticksuffix": chart.secondary_fmt.units,
+                "title_text": chart.secondary_ylabel,
+            },
+        )
     if chart.baseline:
-        _baseline(fig, 0)
+        on_primary, on_secondary = chart._baseline_on()
+        if on_primary:
+            _baseline(fig, 0)
+        if on_secondary:
+            _baseline(fig, 0, yref="y2")
     if chart.fmt.units:
-        fig.update_yaxes(ticksuffix=chart.fmt.units)
+        fig.update_layout(yaxis_ticksuffix=chart.fmt.units)
     _legend_side(fig, chart.legend)
     return fig
 

tesorotools_python-0.1.3/src/tesorotools/artists/sharing.py

@@ -0,0 +1,59 @@
+"""One y scale shared by several separate charts.
+
+Two charts that are read side by side (US and European equities, both
+base 100) mislead when each picks its own y range: the same move looks
+bigger in the flatter one.  Charts that declare the same ``y_group``
+are measured together here and all get the union of their ranges as a
+fixed ``y_limits``, which both backends honour (``build()`` for the PNG,
+``to_plotly()`` for the interactive figure).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+import matplotlib.pyplot as plt
+
+__all__ = ["share_y_axes"]
+
+
+def share_y_axes(charts: Iterable[Any]) -> dict[str, tuple[float, float]]:
+    """Give every chart of each ``y_group`` the same ``y_limits``.
+
+    *charts* is any iterable of artists, typically the values of the
+    mapping loaded from a charts YAML; the ones without a ``y_group``
+    (or with ``None``) are left untouched.  Each grouped chart is built
+    once with its own natural range (the one it would draw alone,
+    including the room its end-of-series labels open), and the group
+    gets the lowest bottom and the highest top among its members.  Call
+    it before ``plot()`` / ``to_plotly()``; calling it again measures
+    afresh, so it is safe after the data change.
+
+    Returns the shared ``(bottom, top)`` per group name.
+    """
+    groups: dict[str, list[Any]] = {}
+    for chart in charts:
+        group: Any = getattr(chart, "y_group", None)
+        if group is not None:
+            groups.setdefault(str(group), []).append(chart)
+
+    shared: dict[str, tuple[float, float]] = {}
+    for name, members in groups.items():
+        bottoms: list[float] = []
+        tops: list[float] = []
+        for chart in members:
+            # measure the chart's own range, not one shared earlier
+            chart.y_limits = None
+            fig, ax = chart.build()
+            try:
+                bottom, top = ax.get_ylim()
+            finally:
+                plt.close(fig)
+            bottoms.append(float(bottom))
+            tops.append(float(top))
+        limits = (min(bottoms), max(tops))
+        for chart in members:
+            chart.y_limits = limits
+        shared[name] = limits
+    return shared