tesorotools-python 0.0.45__tar.gz → 0.0.47__tar.gz

{tesorotools_python-0.0.45 → tesorotools_python-0.0.47}/.gitignore

@@ -24,4 +24,6 @@ test/
 .coverage
 
 # ruff
-.ruff_cache/
+.ruff_cache/
+
+demo_compacto/

{tesorotools_python-0.0.45 → tesorotools_python-0.0.47}/PKG-INFO

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

{tesorotools_python-0.0.45 → tesorotools_python-0.0.47}/src/tesorotools/__init__.py

@@ -49,9 +49,12 @@ from tesorotools.artists import (
     HorizontalBarChart,
     Legend,
     LinePlot,
+    MatrixChart,
     StackedAreaPlot,
     StackedBarPlot,
     TypeCurve,
+    VectorPlot,
+    Waterfall,
 )
 from tesorotools.orchestration import CompositeRegistry, iter_contexts
 from tesorotools.providers.base import (
@@ -79,6 +82,9 @@ 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_artist("waterfall", Waterfall)
 
     register_tag("format", Format)
     register_tag("legend", Legend)
@@ -111,6 +117,7 @@ __all__ = [
     "Legend",
     "LinePlot",
     "LSEGProvider",
+    "MatrixChart",
     "RegistryProtocol",
     "Report",
     "Section",
@@ -121,6 +128,8 @@ __all__ = [
     "Text",
     "Title",
     "TypeCurve",
+    "VectorPlot",
+    "Waterfall",
     "YamlConstructor",
     "all_artists",
     "all_providers",

{tesorotools_python-0.0.45 → tesorotools_python-0.0.47}/src/tesorotools/artists/__init__.py

@@ -29,8 +29,11 @@ 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.artists.waterfall import Waterfall
 from tesorotools.utils.globals import STYLE_SHEET
 
 matplotlib.style.use(STYLE_SHEET)
@@ -42,7 +45,10 @@ __all__ = [
     "HorizontalBarChart",
     "Legend",
     "LinePlot",
+    "MatrixChart",
     "StackedAreaPlot",
     "StackedBarPlot",
     "TypeCurve",
+    "VectorPlot",
+    "Waterfall",
 ]

{tesorotools_python-0.0.45 → tesorotools_python-0.0.47}/src/tesorotools/artists/_common.py

@@ -29,9 +29,14 @@ from typing import Any, Protocol, Self, cast, runtime_checkable
 import matplotlib.pyplot as plt
 import pandas as pd
 from matplotlib.axes import Axes
+from matplotlib.dates import AutoDateLocator, ConciseDateFormatter
+from matplotlib.dates import (
+    date2num,  # type: ignore[reportUnknownVariableType]
+)
 from matplotlib.figure import Figure
 from matplotlib.font_manager import FontProperties
-from matplotlib.ticker import FuncFormatter
+from matplotlib.legend import Legend as MplLegend
+from matplotlib.ticker import FixedLocator, FuncFormatter
 from yaml.nodes import MappingNode
 
 from tesorotools.utils.matplotlib import (
@@ -45,6 +50,9 @@ load_fonts()
 
 AX_CONFIG: dict[str, Any] = PLOT_CONFIG["ax"]
 FIG_CONFIG: dict[str, Any] = PLOT_CONFIG["figure"]
+COMPACT_CONFIG: dict[str, Any] = PLOT_CONFIG.get("compact", {})
+
+CM_TO_IN: float = 1.0 / 2.54
 
 
 # ----------------------------------------------------------------------
@@ -295,6 +303,117 @@ def export_legend(
         legend.remove()
 
 
+# ----------------------------------------------------------------------
+# Compact mode (charts that live inside a Word table, two per row)
+# ----------------------------------------------------------------------
+
+
+def compact_figsize() -> tuple[float, float]:
+    """Return the compact figure size ``(width, height)`` in inches.
+
+    The width is the **total** figure width (chart + legend),
+    read from the ``compact`` section of ``plots.yaml`` in
+    centimetres and converted to inches.  Defaults to
+    7.4 cm x 5.5 cm when the config is absent.
+    """
+    width_cm: float = float(COMPACT_CONFIG.get("width_cm", 7.4))
+    height_cm: float = float(COMPACT_CONFIG.get("height_cm", 5.5))
+    return (width_cm * CM_TO_IN, height_cm * CM_TO_IN)
+
+
+def compact_font_pt() -> float | None:
+    """Font size (points) for compact charts, or ``None`` to keep the style.
+
+    Because the compact figure is rendered at its true
+    physical size (7.4 cm) and embedded without rescaling,
+    these points equal the points the reader sees in Word --
+    set ``compact.font_pt`` in ``plots.yaml`` to the document
+    body-text size so chart text matches running text.
+    """
+    raw: Any = COMPACT_CONFIG.get("font_pt")
+    return None if raw is None else float(raw)
+
+
+def compact_date_axis(
+    ax: Axes,
+    data_min: Any,
+    data_max: Any,
+    *,
+    maxticks: int = 4,
+) -> None:
+    """Compact date x-axis: few horizontal ticks, last one near the data end.
+
+    Ticks are computed over the **data span** ``[data_min,
+    data_max]`` and pinned with a ``FixedLocator``, so none
+    float in the right-hand margin that the value labels open
+    up -- the last tick lands as close to the final data
+    point as the tick step allows.  Requires the series to
+    have been plotted with ``x_compat=True`` (pandas' own
+    date plotting ignores this formatter).
+    """
+    lo: float = float(cast(Any, date2num(data_min)))
+    hi: float = float(cast(Any, date2num(data_max)))
+    locator = AutoDateLocator(minticks=2, maxticks=maxticks)
+    candidates: list[float] = cast(
+        "list[float]", locator.tick_values(data_min, data_max)
+    )
+    ticks: list[float] = [t for t in candidates if lo <= t <= hi]
+    if not ticks:
+        ticks = [lo, hi]
+    fixed = FixedLocator(ticks)
+    ax.xaxis.set_major_locator(fixed)
+    ax.xaxis.set_major_formatter(ConciseDateFormatter(fixed))
+    ax.tick_params(  # type: ignore[reportUnknownMemberType]
+        axis="x", rotation=0
+    )
+    for label in ax.get_xticklabels():
+        label.set_horizontalalignment("center")
+
+
+def legend_above(
+    ax: Axes,
+    handles: list[Any],
+    labels: list[str],
+    *,
+    ncol: int,
+    fontsize: float | None = None,
+) -> MplLegend:
+    """Place the legend **above** the axes, expanded to its full width.
+
+    Uses ``mode="expand"`` so the legend spans exactly the
+    plot width (never wider) and ``bbox_to_anchor`` from the
+    ``compact`` config (default ``(0, 1.06, 1, 0.12)`` -- the
+    ``y0 > 1`` lifts it clear of the axes).  The legend
+    becomes a child of the axes, so constrained layout
+    reserves room for it inside the fixed compact figure.
+    """
+    bbox: Any = COMPACT_CONFIG.get("legend_bbox", [0.0, 1.06, 1.0, 0.12])
+    return ax.legend(  # type: ignore[reportUnknownMemberType]
+        handles,
+        labels,
+        loc="lower left",
+        bbox_to_anchor=tuple(bbox),
+        mode="expand",
+        borderaxespad=0.0,
+        ncol=ncol,
+        fontsize=fontsize,
+        frameon=False,  # no box: less clutter in the tight compact figure
+    )
+
+
+def declutter_spines(ax: Axes) -> None:
+    """Hide the spines that carry no ticks (top and right).
+
+    Compact line charts move the y-ticks to the **left** (so
+    the right edge is free for the end-of-series value labels)
+    and keep x-ticks on the bottom, leaving the top and right
+    spines as pure clutter -- drop them to free space and
+    reduce visual noise.
+    """
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+
+
 # ----------------------------------------------------------------------
 # Cartesian (vertical-y) styling
 # ----------------------------------------------------------------------
@@ -378,6 +497,9 @@ def annotate_last_values(
     labels: dict[str, str] | None = None,
     series_styles: dict[str, dict[str, Any]] | None = None,
     annotate_color: str | None = None,
+    weight: str | None = None,
+    fontsize: float | None = None,
+    right_pad_px: float = 10.0,
 ) -> None:
     """Label the last non-NaN value of each column on the right.
 
@@ -392,8 +514,12 @@ def annotate_last_values(
 
     Labels are packed vertically in display space so that
     series ending at nearly the same value do not overlap.
-    The x-axis limit is extended by the widest label so
-    the text is not clipped by the axes frame.
+    They sit just right of the last point and the x-axis
+    limit is extended by the widest label plus ``right_pad_px``
+    so the text is not clipped by the axes frame; raise
+    ``right_pad_px`` (e.g. on compact charts) to open more
+    blank space on the right and keep the labels clear of both
+    the data lines and the right-hand y-tick labels.
     """
     fig = ax.get_figure()
     if fig is None:
@@ -428,7 +554,7 @@ def annotate_last_values(
     trans = ax.transData
 
     sample = ax.text(  # type: ignore[reportUnknownMemberType]
-        0, 0, "0"
+        0, 0, "0", fontsize=fontsize
     )
     text_height = (
         sample.get_window_extent(renderer).height  # type: ignore[reportUnknownArgumentType]
@@ -459,13 +585,18 @@ def annotate_last_values(
             color=color,
             va="center",
             ha="left",
+            fontweight=weight if weight is not None else "normal",
+            fontsize=fontsize,
         )
         width = t.get_window_extent(renderer).width  # type: ignore[reportUnknownArgumentType]
         max_label_width = max(max_label_width, width)
 
+    # labels spill right of the data, so widen the x-limit by the widest
+    # label plus right_pad_px to keep them unclipped (and, with a larger
+    # pad, clear of the right-hand y-tick labels).
     inv = trans.inverted()
     x0: float = inv.transform((0, 0))[0]  # type: ignore[reportUnknownArgumentType]
-    x1: float = inv.transform((max_label_width + 10, 0))[0]  # type: ignore[reportUnknownArgumentType]
+    x1: float = inv.transform((max_label_width + right_pad_px, 0))[0]  # type: ignore[reportUnknownArgumentType]
     xmin, xmax = ax.get_xlim()
     ax.set_xlim(xmin, xmax + (x1 - x0))
 

{tesorotools_python-0.0.45 → tesorotools_python-0.0.47}/src/tesorotools/artists/line_plot.py

@@ -29,7 +29,12 @@ from tesorotools.artists._common import (
     adjust_figure_for_plot_size,
     annotate_last_values,
     auto_ncol,
+    compact_date_axis,
+    compact_figsize,
+    compact_font_pt,
+    declutter_spines,
     draw_vlines,
+    legend_above,
     style_baseline,
     style_spines,
 )
@@ -60,6 +65,12 @@ class LinePlot:
       (color, linestyle, ...).
     * ``baseline`` -- draw an axhline at 0 (or 100 when
       ``base_100``).
+    * ``compact`` -- render at a fixed physical size (7.4 cm
+      wide *including* the legend, from ``plots.yaml``) for
+      placing two charts per row inside a Word table. Moves
+      the legend above the plot expanded to its width, uses a
+      ``ConciseDateFormatter`` date axis and bold end-of-series
+      labels.
 
     Render lifecycle: ``build()`` returns ``(Figure, Axes)``
     in memory; ``save(fig)`` persists to ``out_path``;
@@ -87,6 +98,7 @@ class LinePlot:
         series_styles: dict[str, dict[str, Any]] | None = None,
         plot_size: tuple[float, float] | None = None,
         vlines: list[dict[str, Any]] | None = None,
+        compact: bool = False,
     ) -> None:
         if out_path.suffix != ".png":
             raise ValueError(f"out_path must be .png: {out_path}")
@@ -108,6 +120,7 @@ class LinePlot:
         self.series_styles = series_styles or {}
         self.plot_size = plot_size
         self.vlines = vlines or []
+        self.compact = compact
 
     @classmethod
     def from_yaml(cls, loader: TemplateLoader, node: MappingNode) -> Self:
@@ -130,7 +143,7 @@ class LinePlot:
         ``base_100_date``, ``annotate``, ``annotate_color``,
         ``baseline``, ``fmt`` (``!format``), ``legend``
         (``!legend``), ``figsize``, ``series_styles``,
-        ``plot_size``, ``vlines``.
+        ``plot_size``, ``vlines``, ``compact``.
 
         Example
         -------
@@ -199,13 +212,30 @@ class LinePlot:
         fig_kw = dict(FIG_CONFIG)
         if self.figsize is not None:
             fig_kw["figsize"] = self.figsize
+        elif self.compact:
+            fig_kw["figsize"] = compact_figsize()
         fig: Figure = plt.figure(  # type: ignore[reportUnknownMemberType]
             **fig_kw
         )
+        font_pt = compact_font_pt() if self.compact else None
+
         ax = fig.add_subplot()
         for col in plot_data.columns:
             style = self.series_styles.get(col, {})
-            plot_data[col].plot(ax=ax, label=self.series[col], **style)
+            # compact mode needs matplotlib's native date axis so the
+            # ConciseDateFormatter takes effect (x_compat disables pandas'
+            # own date plotting machinery).
+            plot_data[col].plot(
+                ax=ax,
+                label=self.series[col],
+                x_compat=self.compact,
+                **style,
+            )
+
+        if self.compact:
+            # no left/right padding: the line starts exactly at the first
+            # data point. annotate_last_values reopens room on the right.
+            ax.margins(x=0)
 
         if self.vlines:
             draw_vlines(ax, self.vlines)
@@ -219,6 +249,18 @@ class LinePlot:
                 labels=self.series,
                 series_styles=self.series_styles,
                 annotate_color=self.annotate_color,
+                weight="bold" if self.compact else None,
+                fontsize=font_pt,
+                # blank space (dynamic, scales with font + dpi) opened past
+                # the label. compact has the y-axis on the LEFT, so half an em
+                # of clearance is enough; normal keeps the y-axis on the RIGHT,
+                # so leave a wider gap to separate the value labels from the
+                # y-tick numbers they would otherwise butt against.
+                right_pad_px=(
+                    0.5 * (font_pt or 12.0) * fig.dpi / 72.0
+                    if self.compact
+                    else 1.6 * plt.rcParams["font.size"] * fig.dpi / 72.0
+                ),
             )
 
         style_spines(
@@ -231,23 +273,54 @@ class LinePlot:
             reference = 100 if self.base_100 else 0
             style_baseline(ax, reference, **AX_CONFIG["baseline"])
 
+        if self.compact:
+            # pin the date ticks to the data span (after annotate widened the
+            # x-limit) so the last tick sits next to the final data point and
+            # none float in the value-label margin; match Word's body font.
+            compact_date_axis(ax, plot_data.index.min(), plot_data.index.max())
+            # compact only: y-numbers on the LEFT so the right edge is free
+            # for the value labels, and drop the now-tickless top/right
+            # spines. Normal mode keeps the house right-hand y-axis and box.
+            ax.yaxis.tick_left()
+            declutter_spines(ax)
+            if font_pt is not None:
+                ax.tick_params(  # type: ignore[reportUnknownMemberType]
+                    axis="both", labelsize=font_pt
+                )
+
         if self.legend is not None:
             labels = [self.series[c] for c in plot_data.columns]
             handles, label_strs = ax.get_legend_handles_labels()
-            fig_width_px: float = fig.get_size_inches()[0] * fig.dpi
-            ncol = (
-                self.legend.ncol
-                if self.legend.ncol is not None
-                else auto_ncol(ax, labels, available_width_px=fig_width_px)
-            )
-            fig.legend(  # type: ignore[reportUnknownMemberType]
-                handles,
-                label_strs,
-                loc="outside lower center",
-                ncol=ncol,
-            )
+            if self.compact:
+                # legend ABOVE the plot, expanded to the plot width. ncol is
+                # auto-fitted to the (narrow) axes width so labels never
+                # overlap; long labels stack into rows. Override the column
+                # count via !legend {ncol: N} when you know they fit.
+                ncol = (
+                    self.legend.ncol
+                    if self.legend.ncol is not None
+                    else auto_ncol(ax, labels)
+                )
+                legend_above(
+                    ax, handles, label_strs, ncol=ncol, fontsize=font_pt
+                )
+            else:
+                fig_width_px: float = fig.get_size_inches()[0] * fig.dpi
+                ncol = (
+                    self.legend.ncol
+                    if self.legend.ncol is not None
+                    else auto_ncol(ax, labels, available_width_px=fig_width_px)
+                )
+                fig.legend(  # type: ignore[reportUnknownMemberType]
+                    handles,
+                    label_strs,
+                    loc="outside lower center",
+                    ncol=ncol,
+                )
 
-        if self.plot_size is not None:
+        # compact mode fixes the *figure* size (width includes the legend),
+        # so the axes-sizing pass would fight it; skip it there.
+        if self.plot_size is not None and not self.compact:
             adjust_figure_for_plot_size(fig, ax, self.plot_size)
 
         return fig, ax