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

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

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

{tesorotools_python-0.1.3 → tesorotools_python-0.1.5}/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.3 → tesorotools_python-0.1.5}/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.3 → tesorotools_python-0.1.5}/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.3 → tesorotools_python-0.1.5}/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
@@ -611,7 +624,7 @@ def compact_legend_font_pt() -> float:
     )
 
 
-def compact_legend_kwargs() -> dict[str, Any]:
+def compact_legend_kwargs(ax: Axes | None = None) -> dict[str, Any]:
     """Legend styling for compact charts, from the ``compact`` config.
 
     Returns ``fontsize`` / ``handlelength`` / ``handletextpad`` /
@@ -620,9 +633,17 @@ def compact_legend_kwargs() -> dict[str, Any]:
     the metrics used to *draw* the legend in :func:`legend_above` -- the
     invariant that prevents an over-counted ``ncol``.  The smaller font
     and shorter handles let several wide labels share one legend row.
+
+    With *ax*, the legend is never larger than its tick labels: a chart
+    drawn with a small ``font_pt`` (the 7 pt of the notes) keeps the
+    legend at that size instead of ``legend_font_pt``.
     """
+    fontsize = compact_legend_font_pt()
+    ticks = (ax.get_yticklabels() or ax.get_xticklabels()) if ax else []
+    if ticks:
+        fontsize = min(fontsize, float(ticks[0].get_fontsize()))
     return {
-        "fontsize": compact_legend_font_pt(),
+        "fontsize": fontsize,
         "handlelength": float(COMPACT_CONFIG.get("legend_handlelength", 1.2)),
         "handletextpad": float(COMPACT_CONFIG.get("legend_handletextpad", 0.4)),
         "columnspacing": float(COMPACT_CONFIG.get("legend_columnspacing", 0.8)),
@@ -980,6 +1001,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 +1049,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])
     )
@@ -1198,7 +1259,7 @@ def place_legend(
     side = resolve_legend_position(position, compact=compact)
     fig_w_px: float = fig.get_size_inches()[0] * fig.dpi
     if compact:
-        legend_kw = compact_legend_kwargs()
+        legend_kw = compact_legend_kwargs(ax)
         if ncol is None:
             ncol = auto_ncol(
                 ax, labels, available_width_px=fig_w_px, **legend_kw
@@ -1288,6 +1349,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.3 → tesorotools_python-0.1.5}/src/tesorotools/artists/bar_line.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__ = ["BarLinePlot"]
 BAR_LINE_CONFIG: dict[str, Any] = PLOT_CONFIG["bar_line"]
 
 
-class BarLinePlot:
+class BarLinePlot(FigureLifecycle):
     """Combo chart: vertical bars and marked lines, optionally on two axes.
 
     Parameters mirror the other time-series artists where they overlap

{tesorotools_python-0.1.3 → tesorotools_python-0.1.5}/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``,
@@ -498,7 +499,7 @@ class BoxPlot:
             self.legend.position, compact=self.compact
         )
         if self.compact:
-            kw = compact_legend_kwargs()
+            kw = compact_legend_kwargs(ax)
             ncol = self.legend.ncol or auto_ncol(
                 ax, labels, available_width_px=fig_w_px, **kw
             )

{tesorotools_python-0.1.3 → tesorotools_python-0.1.5}/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.3 → tesorotools_python-0.1.5}/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"])

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

@@ -20,7 +20,7 @@ never depends on plotly.
 
 Coverage: every image artist except ``IntradayPlot`` -- line, type
 curve, stacked area, stacked bar, bar+line, box, shock, waterfall,
-horizontal bar, grouped bar, matrix and vector.
+horizontal bar, grouped bar, matrix, vector, sankey and scatter.
 
 Known mimicry caveats (the styling that does NOT transfer for free between
 backends, per the dual-backend research):
@@ -64,6 +64,8 @@ if TYPE_CHECKING:
     )
     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.shock_plot import ShockChart
     from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
     from tesorotools.artists.type_curve import TypeCurve
@@ -78,6 +80,8 @@ __all__ = [
     "house_template",
     "line_plot_to_figure",
     "matrix_to_figure",
+    "sankey_to_figure",
+    "scatter_to_figure",
     "shock_chart_to_figure",
     "stacked_area_to_figure",
     "stacked_bar_to_figure",
@@ -1092,3 +1096,140 @@ def vector_plot_to_figure(chart: VectorPlot) -> go.Figure:
         ticksuffix=chart.y_fmt.units or "",
     )
     return fig
+
+
+def sankey_to_figure(chart: SankeyPlot) -> go.Figure:
+    """Interactive ``Figure`` from a :class:`SankeyPlot` (``go.Sankey``).
+
+    Consumes the same layout as ``SankeyPlot.build``: one Plotly node per
+    (stage, node) pair, pinned at its column and at the vertical centre
+    the static chart gives it (``arrangement="fixed"``), and one link per
+    flow coloured like its source node with ``sankey.flow_alpha``.  Node
+    labels carry the node value, as the end columns of the PNG do.
+    """
+    from tesorotools.artists.sankey import SANKEY_CONFIG
+
+    lay = chart._layout()
+    n_col = len(lay.columns)
+    alpha = float(SANKEY_CONFIG.get("flow_alpha", 0.45))
+    index: dict[tuple[int, str], int] = {}
+    labels: list[str] = []
+    colors: list[str] = []
+    xs: list[float] = []
+    ys: list[float] = []
+    for (c, n), top in lay.tops.items():
+        index[(c, n)] = len(labels)
+        height = lay.heights[(c, n)]
+        labels.append(f"{chart.label(n)} {chart.value_text(height)}")
+        colors.append(_color(chart.color(n)))
+        # Plotly pins nodes strictly inside (0, 1); y grows downwards.
+        xs.append(min(max(c / (n_col - 1), 0.001), 0.999))
+        centre = 1 - (top - height / 2) / lay.total_height
+        ys.append(min(max(centre, 0.001), 0.999))
+    fig = _new_figure()
+    fig.add_trace(
+        go.Sankey(
+            arrangement="fixed",
+            valueformat=f".{chart.fmt.decimals}f",
+            valuesuffix=chart.fmt.units or "",
+            node={
+                "label": labels,
+                "color": colors,
+                "x": xs,
+                "y": ys,
+                "pad": 10,
+                "thickness": 12,
+                "line": {"width": 0},
+            },
+            link={
+                "source": [index[(f.column, f.source)] for f in lay.flows],
+                "target": [index[(f.column + 1, f.target)] for f in lay.flows],
+                "value": [f.value for f in lay.flows],
+                "color": [
+                    _color(chart.color(f.source), alpha) for f in lay.flows
+                ],
+            },
+        )
+    )
+    for c, text in enumerate(lay.stage_labels):
+        fig.add_annotation(
+            x=c / (n_col - 1),
+            y=1.06,
+            xref="paper",
+            yref="paper",
+            text=f"<b>{text}</b>",
+            showarrow=False,
+        )
+    return fig
+
+
+#: ``ScatterPlot`` label side -> Plotly ``textposition``.
+_TEXT_POSITION = {
+    "above right": "top right",
+    "below right": "bottom right",
+    "above left": "top left",
+    "below left": "bottom left",
+    "right": "middle right",
+    "left": "middle left",
+    "above": "top center",
+    "below": "bottom center",
+}
+
+
+def scatter_to_figure(chart: ScatterPlot) -> go.Figure:
+    """Interactive ``Figure`` from a :class:`ScatterPlot`.
+
+    One ``go.Scatter`` trace per group (so the legend lists the groups),
+    each point labelled on the side the PNG chose
+    (:meth:`ScatterPlot.placements`), with the same colours and limits.
+    """
+    from tesorotools.artists.scatter import SCATTER_CONFIG
+
+    rows = chart._rows()
+    order = chart.group_order(rows)
+    sides = chart.placements() if chart.labels else {}
+    fig = _new_figure()
+    for group in order:
+        points = rows[rows["group"] == group]
+        color = _color(chart.color(group, order))
+        fig.add_trace(
+            go.Scatter(
+                x=points["x"],
+                y=points["y"],
+                mode="markers+text" if chart.labels else "markers",
+                name=chart.group_label(group),
+                showlegend=bool(chart.group) and chart.legend is not None,
+                text=[chart.series[c] for c in points.index],
+                textposition=[
+                    _TEXT_POSITION[sides.get(str(c), "above right")]
+                    for c in points.index
+                ],
+                textfont={"color": color},
+                marker={
+                    "color": color,
+                    "size": float(SCATTER_CONFIG.get("marker_size", 60)) ** 0.5,
+                    "line": {
+                        "color": _color(
+                            SCATTER_CONFIG.get("edge_color", "#333333")
+                        ),
+                        "width": float(SCATTER_CONFIG.get("edge_width", 0.8)),
+                    },
+                },
+                hovertemplate="%{text}: %{x}, %{y}<extra></extra>",
+            )
+        )
+    fig.update_layout(
+        xaxis={
+            "range": list(chart.limits(rows["x"], "x")),
+            "title_text": chart.xlabel,
+            "ticksuffix": chart.x_fmt.units,
+            "showgrid": True,
+        },
+        yaxis={
+            "range": list(chart.limits(rows["y"], "y")),
+            "title_text": chart.ylabel,
+            "ticksuffix": chart.y_fmt.units,
+        },
+    )
+    _legend_side(fig, chart.legend)
+    return fig