tesorotools-python 0.1.11__tar.gz → 0.1.12__tar.gz

{tesorotools_python-0.1.11 → tesorotools_python-0.1.12}/PKG-INFO

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

tesorotools_python-0.1.12/src/tesorotools/artists/_bars.py

@@ -0,0 +1,231 @@
+"""Category x-axes of the vertical bar charts: labels that never collide.
+
+Shared by :class:`~tesorotools.artists.stacked.StackedBarPlot`,
+:class:`~tesorotools.artists.bar_line.BarLinePlot` and
+:class:`~tesorotools.artists.waterfall.Waterfall`, whose bars sit one per
+slot (``np.arange``) rather than on a date axis.  A dated slot axis is
+labelled on the calendar grid of :mod:`tesorotools.artists._dates` (every
+year, quarter or month boundary that fits), and any label row turns only
+when it does not fit flat.  Measured on the drawn figure, like the date
+axes of :mod:`tesorotools.artists._common`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from matplotlib.text import Text
+
+from tesorotools.artists._common import (
+    COMPACT_CONFIG,
+    LINE_CONFIG,
+    date_max_labels,
+)
+from tesorotools.artists._dates import (
+    data_frequency,
+    date_layouts,
+    month_label,
+    quarter_label,
+)
+from tesorotools.utils.matplotlib import PLOT_CONFIG
+
+__all__ = [
+    "bar_date_ticks",
+    "fit_x_rotation",
+    "labels_collide",
+]
+
+BAR_AXIS_CONFIG: dict[str, Any] = PLOT_CONFIG.get("bar_axis", {})
+
+# label texts tried, coarsest first, when no calendar step suits the
+# bars (a few weeks of daily data): the first one that tells them apart.
+# The house forms of the date axes: 2024, mar. 2024, 4 mar., 4 mar. 2024
+_FALLBACK_LABELS: tuple[Callable[[pd.Timestamp], str], ...] = (
+    lambda moment: str(moment.year),
+    lambda moment: month_label(moment, year=True),
+    lambda moment: f"{moment.day} {month_label(moment)}",
+    lambda moment: f"{moment.day} {month_label(moment, year=True)}",
+)
+
+#: The calendar steps finer than a frequency, which would name each bar
+#: by a month it only ends in (``dic.`` under a yearly bar).
+_TOO_FINE: dict[str, tuple[str, ...]] = {
+    "Y": ("1M", "2M", "3M", "6M"),
+    "Q": ("1M", "2M"),
+}
+
+
+def _gap_px(fig: Figure, texts: Sequence[Text], *, compact: bool) -> float:
+    """The air two neighbour labels need, ``date_label_gap_em`` of their size."""
+    cfg = COMPACT_CONFIG if compact else LINE_CONFIG
+    em = float(cfg.get("date_label_gap_em", 0.3))
+    size = max(float(t.get_fontsize()) for t in texts)
+    return em * size * fig.dpi / 72
+
+
+def labels_collide(
+    fig: Figure, texts: Sequence[Text], *, compact: bool = False
+) -> bool:
+    """Whether two neighbouring *texts*, left to right, overlap or touch.
+
+    Empty texts are skipped; the gap two labels need is the date axes'
+    ``date_label_gap_em`` (``compact.`` or ``line.`` in ``plots.yaml``).
+    """
+    shown = [t for t in texts if t.get_visible() and t.get_text()]
+    if len(shown) < 2:
+        return False
+    fig.draw_without_rendering()
+    gap = _gap_px(fig, shown, compact=compact)
+    boxes = sorted((t.get_window_extent() for t in shown), key=lambda b: b.x0)
+    return any(
+        a.x1 + gap > b.x0 and a.y0 < b.y1 and b.y0 < a.y1
+        for a, b in zip(boxes, boxes[1:])
+    )
+
+
+def _set_rotation(ax: Axes, rotation: float) -> None:
+    for label in ax.get_xticklabels():
+        label.set_rotation(rotation)
+        label.set_horizontalalignment("right" if rotation else "center")
+        label.set_rotation_mode("anchor" if rotation else "default")
+
+
+def fit_x_rotation(
+    fig: Figure, ax: Axes, rotation: float | None, *, compact: bool = False
+) -> None:
+    """Turn the x labels only when they do not fit flat.
+
+    ``rotation=None`` (auto) leaves the labels horizontal unless two of
+    them collide, and then turns them ``bar_axis.x_rotation`` degrees
+    (``plots.yaml``); an explicit *rotation* is applied as given.
+    """
+    if rotation is None:
+        _set_rotation(ax, 0)
+        if not labels_collide(fig, ax.get_xticklabels(), compact=compact):
+            return
+        rotation = float(BAR_AXIS_CONFIG.get("x_rotation", 45))
+    _set_rotation(ax, rotation)
+
+
+def _calendar_slots(
+    dates: pd.DatetimeIndex,
+    step: str,
+    ticks: Sequence[pd.Timestamp],
+    frequency: str = "M",
+) -> tuple[list[int], list[str]]:
+    """The first bar of each period of *step* that starts at a tick.
+
+    A period with no bar of its own (a gap in the data) gets no label, so
+    a label always names the bar under it and no two labels repeat.  The
+    labels read as on the date axes of the line charts: the year where
+    a year starts, else the month (``mar.``), the first one with its year
+    (``may. 2024``).  Quarterly bars (*frequency* ``"Q"``) on a month
+    step name their quarter instead, with its year on the first label and
+    on every first quarter (``1T 2024``, ``2T``, ``3T``).
+    """
+    n = int(step[:-1])
+    span = (
+        pd.DateOffset(years=n)
+        if step.endswith("Y")
+        else pd.DateOffset(months=n)
+    )
+    positions: list[int] = []
+    texts: list[str] = []
+    for tick in ticks:
+        i = int(dates.searchsorted(tick))
+        if i < len(dates) and dates[i] < tick + span:
+            positions.append(i)
+            # the year on a year step and where a year starts, as the
+            # date axes do; the first month carries its year too
+            if step.endswith("Y"):
+                texts.append(str(dates[i].year))
+            elif frequency == "Q":
+                texts.append(
+                    quarter_label(
+                        dates[i], year=not texts or dates[i].quarter == 1
+                    )
+                )
+            elif tick.month == 1:
+                texts.append(str(dates[i].year))
+            else:
+                texts.append(month_label(dates[i], year=not texts))
+    return positions, texts
+
+
+def _fallback_slots(
+    dates: pd.DatetimeIndex, every: int
+) -> tuple[list[int], list[str]]:
+    """Every *every*-th bar, in the coarsest format that tells them apart."""
+    positions = list(range(0, len(dates), every))
+    rows = [[label(dates[i]) for i in positions] for label in _FALLBACK_LABELS]
+    return positions, next(
+        (texts for texts in rows if len(set(texts)) == len(texts)), rows[-1]
+    )
+
+
+def bar_date_ticks(
+    fig: Figure,
+    ax: Axes,
+    dates: pd.DatetimeIndex,
+    *,
+    compact: bool = False,
+    rotation: float | None = None,
+    pin_start: bool = True,
+) -> None:
+    """Label one bar per calendar period, as many periods as fit.
+
+    The candidates are the calendar steps of the date axes (every year,
+    every 2, 5... years and, over spans up to ``date_monthly_max_months``,
+    every month or quarter), finest first, none finer than the bars
+    themselves (:func:`~tesorotools.artists._dates.data_frequency`):
+    yearly bars read ``2023 2024 2025`` and not ``dic. 2023 dic. dic.``,
+    quarterly ones ``1T 2024 2T 3T`` (over up to three times
+    ``date_monthly_max_months``); each labels the first bar of
+    its period, and the finest whose labels fit across the axis (at
+    *rotation*, flat when ``None``) and stay within the mode's
+    ``date_max_labels`` wins.  When no calendar step suits the span, every
+    k-th bar is labelled instead, k as small as fits.  With *pin_start*
+    the first bar is labelled too (its year, or month), as the date axes
+    of ``date_show_start`` do, so the reader sees when the series starts.
+    """
+    cfg = COMPACT_CONFIG if compact else LINE_CONFIG
+    frequency = data_frequency(dates)
+    # a quarter is a third of the bars a month gives over the same span:
+    # quarterly bars name their quarters over three times the span
+    months = int(cfg.get("date_monthly_max_months", 24))
+    layouts = date_layouts(
+        dates.min(),
+        dates.max(),
+        step="auto",
+        max_labels=date_max_labels("default", compact=compact),
+        monthly_max_months=months * (3 if frequency == "Q" else 1),
+        pin_start=pin_start,
+    )
+    too_fine = _TOO_FINE.get(frequency, ())
+    candidates = [
+        _calendar_slots(dates, layout.step, layout.ticks, frequency)
+        for layout in layouts
+        if layout.step not in too_fine
+    ]
+    candidates = [c for c in candidates if len(c[0]) >= 2]
+    # no calendar step suits the span, or none fits: every k-th bar, from
+    # the k that keeps within the label count up to a single label
+    most = date_max_labels("default", compact=compact)
+    first = max(1, -(-len(dates) // most))  # ceil
+    candidates += [
+        _fallback_slots(dates, every) for every in range(first, len(dates) + 1)
+    ]
+    for positions, texts in candidates:
+        ax.set_xticks(  # type: ignore[reportUnknownMemberType]
+            positions
+        )
+        ax.set_xticklabels(  # type: ignore[reportUnknownMemberType]
+            texts
+        )
+        _set_rotation(ax, rotation or 0)
+        if not labels_collide(fig, ax.get_xticklabels(), compact=compact):
+            return