djrhails-graphs 0.1.0__py3-none-any.whl

djrhails_graphs-0.1.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: djrhails-graphs
+Version: 0.1.0
+Summary: Economist-style chart theme for matplotlib/seaborn
+Author-email: Daniel Hails <graphs@hails.info>
+Project-URL: Homepage, https://github.com/DJRHails/graphs
+Project-URL: Bug Tracker, https://github.com/DJRHails/graphs/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# graphs
+
+Economist-style chart theme for matplotlib and seaborn — global theme, title-stack
+finaliser, direct line labels, CI bands, horizontal bars, and dumbbell charts.
+Uses IBM Plex Sans typography and a curated 8-colour palette.
+
+Version: 0.1.0
+
+## Install
+
+```bash
+pip install djrhails-graphs
+```
+
+PyPI distribution is `djrhails-graphs` because the bare name `graphs` is taken.
+The import package is `graphs`.
+
+## Quick start
+
+```python
+import matplotlib.pyplot as plt
+from graphs import ci_fill, finalize, label_lines, set_theme
+
+set_theme()
+
+fig, ax = plt.subplots()
+fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+
+ax.plot(x, y, label="Series A")
+label_lines(ax)
+finalize(
+    ax,
+    title="Bold chart title",
+    descriptor="Country, metric, unit",
+    source="Source: Organisation",
+)
+```
+
+See `examples/` for runnable scripts:
+
+- `line_chart.py` — multi-series line with CI bands + direct labels
+- `faceted_chart.py` — three-panel faceted layout with panel labels
+- `bar_chart.py` — horizontal bar with max-value highlight
+- `dumbbell_chart.py` — before/after comparison with legend
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `set_theme()` | Apply global rcParams (figure, axes, ticks, fonts, palette) |
+| `finalize(ax, title, descriptor, source, *, y_axis_right, title_x, y_start, autoscale_y)` | Title stack, red rule, source line, y-axis tidy-up |
+| `label_lines(ax, ...)` | Direct end-of-line labels with collision avoidance |
+| `smart_legend(ax, ...)` | Pick the emptiest corner of the axes |
+| `ci_fill(ax, x, y_lo, y_hi, *, color)` | Confidence-interval band |
+| `bar_h(ax, categories, values, *, highlight_max)` | Horizontal bar chart |
+| `dumbbell(ax, categories, start, end, ...)` | Dot-and-line before/after chart |
+| `panel_label(ax, label)` | Bold panel sub-heading for facets |
+
+### Palette
+
+```python
+from graphs import colors, C_BG, C_RED, C_SPINE, C_GRID, C_LABEL, C_TEXT, C_CI
+```
+
+Sequence `colors` (red primary, blue, teal, green, yellow, mauve, slate, coral).
+
+### Typography
+
+IBM Plex Sans is loaded automatically. If already registered in matplotlib's
+font manager, no download occurs. Otherwise TTFs are fetched from
+`github.com/IBM/plex` on first use and cached inside the installed package.
+
+Fallback chain: IBM Plex Sans → Verdana → Arial → DejaVu Sans.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

djrhails_graphs-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+djrhails_graphs-0.1.0.dist-info/licenses/LICENSE,sha256=RjexM-UPby8fRPlfzBjGcbGkb-awdO-A5pngqiggAAw,1069
+examples/bar_chart.py,sha256=K4aOd7MXlws2rWXqu4cNs8gHR_lv7NyEaNTExxMszo4,889
+examples/dumbbell_chart.py,sha256=yQr_u0txoBiFG19rPiNKxU_WW-L6psVmZBa1nIwU2PM,1542
+examples/faceted_chart.py,sha256=_3oHGWrxf8n89TNx2aGMFRzbyM9Ug-P92bHdkvJymX4,2259
+examples/line_chart.py,sha256=XpOsbF8TKEJ1RrEzgXcMCBTN5jjGXGadLs0b7YQVvH0,1334
+graphs/__init__.py,sha256=oP_Ub6NIKWv0Xs3FC1nWsIy6HxmsDrEuNKlt-0j32X4,1074
+graphs/_charts.py,sha256=oxNaRjqISoE80FcL-arSgmXKXCGZht8QR26PC1W2fps,3415
+graphs/_finalize.py,sha256=RG_y5Duci_nRDlhoycWdA3Cc0GPLpoZ-dNaf69IB8w0,7970
+graphs/_fonts.py,sha256=DdtmZoxd7Cy_pm2X_UAeLYU-lFqs8P3bdoUaxb3qasc,1761
+graphs/_labels.py,sha256=9T1fW68F2OCQc9w-Cw5JURM8s1ZLIKAHDwQ_5rfva8Q,7405
+graphs/_legend.py,sha256=5zk9kktLCCx0AiAJpJZyHERegGWRLqqFJxUYufGMoTw,4424
+graphs/_palette.py,sha256=39uvvaTcwEt1PpFgqq2INxqcVEpQuzsV0tE7oXJtRRg,500
+graphs/_theme.py,sha256=j7M1_kDB_KVKg2Urobf9YJwQKwSyIFLSlqhi1OfdOtc,2148
+djrhails_graphs-0.1.0.dist-info/METADATA,sha256=_QltfRoUeuhsTogW93O9fEUfS-ZAIwJT7niOS9Xc0vc,2852
+djrhails_graphs-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+djrhails_graphs-0.1.0.dist-info/top_level.txt,sha256=2AnvJf9GNUDwX0mmiuHIfWKk6oF5FH1ZG7Yibe0Slbs,16
+djrhails_graphs-0.1.0.dist-info/RECORD,,

djrhails_graphs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

djrhails_graphs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Hails
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

djrhails_graphs-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+examples
+graphs

examples/bar_chart.py

@@ -0,0 +1,38 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib"]
+# ///
+"""Horizontal bar chart — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+
+from graphs import bar_h, finalize, set_theme
+
+set_theme()
+
+categories = ["Germany", "France", "Italy", "Spain", "Poland", "Sweden"]
+values = [3.7, 2.4, 1.8, 2.1, 4.2, 3.1]
+
+fig, ax = plt.subplots(figsize=(7, 4))
+fig.subplots_adjust(top=0.62, bottom=0.10, left=0.14, right=0.90)
+
+bar_h(ax, categories, values)
+
+finalize(
+    ax,
+    title="Eastern promise",
+    descriptor="GDP growth rate, %, 2023",
+    source="Source: Eurostat",
+    y_axis_right=False,
+    title_x=0.02,
+)
+
+out = Path(__file__).resolve().parent / "economist_bar.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved bar chart")

examples/dumbbell_chart.py

@@ -0,0 +1,72 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib"]
+# ///
+"""Dumbbell chart — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+
+from graphs import dumbbell, finalize, set_theme
+
+set_theme()
+
+countries = [
+    "United States",
+    "China",
+    "Germany",
+    "Japan",
+    "India",
+    "Brazil",
+]
+gdp_2000 = [10.25, 1.21, 1.95, 4.72, 0.47, 0.65]
+gdp_2020 = [20.93, 14.72, 3.84, 5.06, 2.62, 1.44]
+
+fig, ax = plt.subplots(figsize=(8, 4.5))
+fig.subplots_adjust(top=0.62, bottom=0.12, left=0.18, right=0.88)
+
+dumbbell(
+    ax,
+    countries,
+    gdp_2000,
+    gdp_2020,
+    label_start="2000",
+    label_end="2020",
+)
+ax.set_xlim(-0.5, 24)
+ax.xaxis.set_major_formatter(
+    ticker.FuncFormatter(lambda v, _: f"${v:.0f}tn")
+)
+
+finalize(
+    ax,
+    title="The great divergence",
+    descriptor="GDP in current US dollars, selected economies",
+    source="Source: World Bank",
+    y_axis_right=False,
+    title_x=0.02,
+)
+
+bbox = ax.get_position()
+fig.legend(
+    handles=ax._dumbbell_handles,
+    labels=["2000", "2020"],
+    loc="upper right",
+    bbox_to_anchor=(bbox.x1, bbox.y1 + 0.005),
+    bbox_transform=fig.transFigure,
+    frameon=False,
+    fontsize=8.5,
+    ncol=2,
+    handletextpad=0.4,
+    columnspacing=1.0,
+)
+
+out = Path(__file__).resolve().parent / "economist_dumbbell.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved dumbbell chart")

examples/faceted_chart.py

@@ -0,0 +1,86 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib", "numpy"]
+# ///
+"""Faceted line chart with panel labels — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+import numpy as np
+
+from graphs import (
+    C_BG,
+    C_LABEL,
+    C_RED,
+    C_SPINE,
+    ci_fill,
+    finalize,
+    panel_label,
+    set_theme,
+)
+
+set_theme()
+
+np.random.seed(7)
+x = np.linspace(-6, 10, 80)
+panels = {
+    "Economic": np.where(
+        x < 0, x * 0.01, np.cumsum(np.random.randn(80) * 0.015)
+    ),
+    "Violent": np.cumsum(np.random.randn(80) * 0.008),
+    "Sexual": np.cumsum(np.random.randn(80) * 0.006),
+}
+
+fig, axes = plt.subplots(1, 3, figsize=(10, 5.5), sharey=False)
+fig.subplots_adjust(
+    top=0.72, bottom=0.16, left=0.04, right=0.97, wspace=0.35
+)
+
+for ax, (panel_name, y) in zip(axes, panels.items()):
+    ci = np.abs(np.random.randn(len(x))) * 0.025 + 0.01
+    ci_fill(ax, x, y - ci, y + ci)
+    ax.plot(x, y, color=C_RED, linewidth=2)
+    ax.axhline(0, color=C_SPINE, linewidth=0.8, zorder=3)
+    ax.scatter([0], [0], color=C_SPINE, s=40, zorder=5)
+
+    ax.yaxis.set_label_position("right")
+    ax.yaxis.tick_right()
+    ax.spines["right"].set_visible(True)
+    ax.spines["right"].set_color(C_BG)
+    ax.spines["bottom"].set_color(C_SPINE)
+    ax.spines[["top", "left"]].set_visible(False)
+    ax.yaxis.set_tick_params(pad=-2, labelsize=8.5)
+    ax.set_ylim(-0.22, 0.22)
+    ax.yaxis.set_major_formatter(ticker.FormatStrFormatter("%.1f"))
+    ax.set_xlabel(
+        "Years since cancer diagnosis (1980-2018)",
+        fontsize=8,
+        color=C_LABEL,
+    )
+    panel_label(ax, panel_name)
+
+finalize(
+    axes[0],
+    title=(
+        "Denmark, criminal-conviction rate since\n"
+        "cancer diagnosis, by type of offense"
+    ),
+    descriptor="Percentage-point change from baseline",
+    source=(
+        'Source: "Breaking bad", '
+        "American Economics Journal, 2026"
+    ),
+    y_axis_right=False,
+    title_x=0.04,
+    y_start=0.075,
+)
+
+out = Path(__file__).resolve().parent / "economist_facet.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved facet chart")

examples/line_chart.py

@@ -0,0 +1,50 @@
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["matplotlib", "numpy"]
+# ///
+"""Line chart with CI bands and direct labels — The Economist style."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import matplotlib.pyplot as plt
+import matplotlib.ticker as ticker
+import numpy as np
+
+from graphs import ci_fill, finalize, label_lines, set_theme
+
+set_theme()
+
+np.random.seed(42)
+years = np.arange(2000, 2024)
+data = {
+    "United States": np.cumsum(np.random.randn(24) * 1.5) + 100,
+    "China": np.cumsum(np.random.randn(24) * 2.0) + 100,
+    "Germany": np.cumsum(np.random.randn(24) * 1.0) + 100,
+}
+
+fig, ax = plt.subplots()
+fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+
+for col, y in data.items():
+    ci = np.abs(np.random.randn(len(years))) * 2.5 + 0.5
+    ci_fill(ax, years, y - ci, y + ci)
+    ax.plot(years, y, label=col)
+
+label_lines(ax, stroke=True, min_sep_pct=6.0)
+ax.yaxis.set_major_formatter(ticker.FormatStrFormatter("%.0f"))
+
+finalize(
+    ax,
+    title="GDP across major economies",
+    descriptor="Index, 2000=100",
+    source="Sources: IMF; World Bank",
+    y_axis_right=True,
+)
+
+out = Path(__file__).resolve().parent / "economist_line.png"
+plt.savefig(out, bbox_inches="tight", dpi=150)
+plt.close()
+print("Saved line chart")

graphs/__init__.py

@@ -0,0 +1,52 @@
+"""graphs — Economist-style chart theme for matplotlib/seaborn.
+
+Usage::
+
+    from graphs import set_theme, finalize, colors
+    set_theme()
+
+    fig, ax = plt.subplots()
+    fig.subplots_adjust(top=0.68, bottom=0.14, left=0.06, right=0.88)
+    ax.plot(...)
+    finalize(ax, title="Bold headline", descriptor="Country, metric, unit",
+             source="Source: Organisation")
+"""
+
+from graphs._charts import bar_h, ci_fill, dumbbell
+from graphs._finalize import finalize, panel_label
+from graphs._fonts import _get_font as get_font
+from graphs._labels import label_lines
+from graphs._legend import smart_legend
+from graphs._palette import (
+    C_BG,
+    C_CI,
+    C_GRID,
+    C_LABEL,
+    C_RED,
+    C_SPINE,
+    C_TEXT,
+    colors,
+)
+from graphs._theme import set_theme
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "bar_h",
+    "ci_fill",
+    "colors",
+    "C_BG",
+    "C_CI",
+    "C_GRID",
+    "C_LABEL",
+    "C_RED",
+    "C_SPINE",
+    "C_TEXT",
+    "dumbbell",
+    "finalize",
+    "get_font",
+    "label_lines",
+    "panel_label",
+    "set_theme",
+    "smart_legend",
+]

graphs/_charts.py

@@ -0,0 +1,114 @@
+"""Reusable Economist-style chart helpers."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from graphs._palette import C_CI, C_GRID, C_LABEL, C_RED, C_SPINE, colors
+
+
+def ci_fill(ax, x, y_lower, y_upper, *, color: str | None = None, alpha: float = 0.20):
+    """Fill a confidence-interval band.
+
+    By default uses the Economist salmon (#f5c5b8) at full opacity — the
+    legacy behaviour, fine for charts with a single series. When a colour is
+    provided, draws a semi-transparent fill in that colour so the band visibly
+    matches its line. Pair with `ax.plot(..., color=col)` and pass the same
+    `col` here.
+
+    Args:
+        color: Fill colour. Pass the matching line colour to colour-match.
+        alpha: Opacity when `color` is given. Ignored when `color` is None.
+    """
+    if color is None:
+        ax.fill_between(x, y_lower, y_upper, color=C_CI, linewidth=0, zorder=1)
+    else:
+        ax.fill_between(x, y_lower, y_upper, color=color, alpha=alpha, linewidth=0, zorder=1)
+
+
+def bar_h(
+    ax,
+    categories: Sequence[str],
+    values: Sequence[float],
+    *,
+    color: str | None = None,
+    highlight_max: bool = True,
+):
+    """Horizontal bar chart in Economist style.
+
+    Category labels sit right-aligned to the left of the bars.
+    The highest-value bar is highlighted in red.
+    """
+    color = color or colors[1]
+    bars = ax.barh(categories, values, color=color, height=0.6, zorder=2)
+
+    if highlight_max and values:
+        idx, _ = max(enumerate(values), key=lambda x: x[1])
+        bars[idx].set_color(C_RED)
+
+    ax.spines[["top", "left", "right", "bottom"]].set_visible(False)
+    ax.set_yticks(range(len(categories)))
+    ax.set_yticklabels(categories, ha="right", fontsize=9)
+    ax.yaxis.set_tick_params(length=0, pad=6)
+    ax.xaxis.set_tick_params(labelsize=9, length=3.5, direction="out")
+    ax.grid(axis="x", color=C_GRID, linewidth=0.6, zorder=0)
+    ax.grid(axis="y", visible=False)
+    return ax
+
+
+def dumbbell(
+    ax,
+    categories: Sequence[str],
+    values_start: Sequence[float],
+    values_end: Sequence[float],
+    *,
+    label_start: str = "Start",
+    label_end: str = "End",
+    color_start: str | None = None,
+    color_end: str | None = None,
+):
+    """Dumbbell (dot-and-line) chart for showing change between two periods.
+
+    Scatter handles are stored on ``ax._dumbbell_handles`` so you
+    can pass them to ``fig.legend()`` afterwards.
+    """
+    color_start = color_start or colors[7]  # Coral
+    color_end = color_end or colors[1]  # Blue
+
+    ax.hlines(
+        y=categories,
+        xmin=values_start,
+        xmax=values_end,
+        color=C_LABEL,
+        linewidth=2,
+        alpha=0.6,
+        zorder=2,
+        label="_nolegend_",
+    )
+
+    s1 = ax.scatter(
+        values_start,
+        categories,
+        s=80,
+        color=color_start,
+        zorder=4,
+        label=label_start,
+    )
+    s2 = ax.scatter(
+        values_end,
+        categories,
+        s=80,
+        color=color_end,
+        zorder=4,
+        label=label_end,
+    )
+
+    ax.spines[["top", "left", "right"]].set_visible(False)
+    ax.spines["bottom"].set_color(C_SPINE)
+    ax.yaxis.set_tick_params(length=0, pad=6)
+    ax.xaxis.set_tick_params(labelsize=9, length=3.5, direction="out")
+    ax.grid(axis="x", color=C_GRID, linewidth=0.6, zorder=0)
+    ax.grid(axis="y", visible=False)
+
+    ax._dumbbell_handles = [s1, s2]
+    return ax

graphs/_finalize.py

@@ -0,0 +1,254 @@
+"""Chart finalisation — title stack, source line, panel labels."""
+
+import warnings
+
+import matplotlib.font_manager as fm
+import matplotlib.pyplot as plt
+
+from graphs._fonts import _get_font
+from graphs._palette import C_BG, C_LABEL, C_RED, C_SPINE, C_TEXT
+
+
+def _check_x_monotonic(ax) -> None:
+    """Warn if the x-axis runs right-to-left (e.g. accidental invert_xaxis)."""
+    x0, x1 = ax.get_xlim()
+    if x0 > x1:
+        warnings.warn(
+            "graphs.finalize: x-axis runs right-to-left "
+            f"(xlim={x0:.3g} → {x1:.3g}). If this is unintended, remove the "
+            "invert_xaxis() call or fix the data order.",
+            stacklevel=3,
+        )
+
+
+def _autoscale_y(ax, *, headroom: float = 0.10, floor_frac: float = 0.40) -> None:
+    """Tighten y-limits when data uses less than `floor_frac` of the range.
+
+    Leaves an explicit user-set y-limit alone (detected by the autoscale flag).
+    Skips axes with no real data extent. Adds `headroom` proportional padding
+    above the data so the top line/bar doesn't collide with the spine.
+    """
+    if not ax.get_autoscaley_on():
+        return  # user pinned ylim explicitly
+
+    data_max = float("-inf")
+    data_min = float("inf")
+    for art in list(ax.lines) + list(ax.patches) + list(ax.collections):
+        try:
+            dp = art.get_datalim(ax.transData) if hasattr(art, "get_datalim") else None
+        except Exception:
+            dp = None
+        if dp is not None and dp.height > 0:
+            data_min = min(data_min, dp.y0)
+            data_max = max(data_max, dp.y1)
+
+    # Fallback: scan line ydata.
+    if not (data_max > float("-inf") and data_min < float("inf")):
+        for line in ax.lines:
+            ys = line.get_ydata()
+            if len(ys):
+                data_min = min(data_min, float(min(ys)))
+                data_max = max(data_max, float(max(ys)))
+
+    if not (data_max > float("-inf") and data_min < float("inf")):
+        return
+    if data_max == data_min:
+        return
+
+    y_lo, y_hi = ax.get_ylim()
+    span_used = (data_max - data_min) / (y_hi - y_lo) if y_hi > y_lo else 1.0
+    if span_used >= floor_frac:
+        return
+
+    pad = (data_max - data_min) * headroom
+    new_lo = max(y_lo, data_min - pad) if data_min >= 0 else data_min - pad
+    # Snap to 0 if data is non-negative and close to 0 — keeps the baseline clean.
+    if data_min >= 0 and data_min <= (data_max - data_min) * 0.25:
+        new_lo = 0.0
+    new_hi = data_max + pad
+    ax.set_ylim(new_lo, new_hi)
+
+
+def finalize(
+    ax,
+    title: str = "",
+    descriptor: str = "",
+    source: str = "",
+    *,
+    y_axis_right: bool = True,
+    title_x: float | None = None,
+    y_start: float = 0.010,
+    autoscale_y: bool = True,
+):
+    """Add Economist finishing touches to an axes object.
+
+    Title stack (top to bottom)::
+
+        ────        short red rule
+        Title       IBM Plex Sans Bold
+        Descriptor  IBM Plex Sans Regular
+
+    Args:
+        title: Chart headline.
+        descriptor: Subtitle line (country, metric, unit).
+        source: Attribution line below the chart.
+        y_axis_right: Move y-axis labels to the right.
+        title_x: Override x anchor in figure coords.
+            Defaults to the axes bounding-box x0.
+            Set to e.g. 0.02 for charts with wide left margins.
+        y_start: Gap above bbox.y1 where title stack begins.
+            Increase to ~0.07 for faceted charts.
+        autoscale_y: If True (default), auto-tighten y-limits when the data
+            fills less than 40% of the current axis range. Disable for charts
+            that need a pinned 0–100% canvas regardless of data.
+    """
+    fig = ax.get_figure()
+    fig.patch.set_facecolor(C_BG)
+
+    _check_x_monotonic(ax)
+    if autoscale_y:
+        _autoscale_y(ax)
+
+    if y_axis_right:
+        ax.yaxis.set_label_position("right")
+        ax.yaxis.tick_right()
+        ax.spines["right"].set_visible(True)
+        ax.spines["right"].set_color(C_BG)
+        ax.spines["right"].set_linewidth(0)
+        ax.spines["left"].set_visible(False)
+
+    ax.yaxis.set_tick_params(pad=4, labelsize=9)
+    ax.spines["bottom"].set_color(C_SPINE)
+    ax.spines["bottom"].set_linewidth(1.0)
+
+    fig.canvas.draw()
+    bbox = ax.get_position()
+    tx = title_x if title_x is not None else bbox.x0
+
+    # Build title stack upward from just above the axes
+    line_gap = 0.013
+    rule_gap = 0.026
+    y_cursor = bbox.y1 + y_start
+
+    if descriptor:
+        n_desc_lines = descriptor.count("\n") + 1
+        fig.text(
+            tx,
+            y_cursor,
+            descriptor,
+            transform=fig.transFigure,
+            fontsize=9.5,
+            fontweight="normal",
+            color=C_TEXT,
+            va="bottom",
+            ha="left",
+            linespacing=1.25,
+        )
+        # 0.032 is the height of one descriptor line in figure coords;
+        # add 0.022 per extra line so the title sits clear of the wrap.
+        y_cursor += 0.032 + 0.022 * (n_desc_lines - 1) + line_gap
+
+    if title:
+        fp = fm.FontProperties(family=_get_font(), weight=700)
+        fig.text(
+            tx,
+            y_cursor,
+            title,
+            transform=fig.transFigure,
+            fontsize=12,
+            fontproperties=fp,
+            color=C_TEXT,
+            va="bottom",
+            ha="left",
+        )
+        y_cursor += 0.040 + rule_gap
+
+    # Short red rule at the top (~80 px wide)
+    rule_w = 80 / (fig.get_figwidth() * fig.dpi)
+    fig.add_artist(
+        plt.Line2D(
+            [tx, tx + rule_w],
+            [y_cursor, y_cursor],
+            transform=fig.transFigure,
+            color=C_RED,
+            linewidth=3.5,
+            solid_capstyle="butt",
+            clip_on=False,
+        )
+    )
+
+    if source:
+        # Place source below the lowest of: xlabel, x-tick labels.
+        # Wrapped multi-line x-tick labels can extend further down than the
+        # xlabel and previously caused the source line to overlap them.
+        source_y = bbox.y0 - 0.06
+        try:
+            renderer = fig.canvas.get_renderer()
+            lowest_fig_y = bbox.y0
+            xlabel = ax.xaxis.label
+            if xlabel.get_text():
+                xlbl_bbox = xlabel.get_window_extent(renderer=renderer)
+                lowest_fig_y = min(
+                    lowest_fig_y,
+                    xlbl_bbox.transformed(fig.transFigure.inverted()).y0,
+                )
+            for tl in ax.get_xticklabels():
+                if not tl.get_text():
+                    continue
+                tl_bb = tl.get_window_extent(renderer=renderer)
+                lowest_fig_y = min(
+                    lowest_fig_y,
+                    tl_bb.transformed(fig.transFigure.inverted()).y0,
+                )
+            source_y = min(source_y, lowest_fig_y - 0.015)
+        except Exception:
+            pass
+        fig.text(
+            tx,
+            source_y,
+            source,
+            transform=fig.transFigure,
+            fontsize=7.5,
+            color=C_LABEL,
+            va="top",
+            ha="left",
+        )
+
+    return fig, ax
+
+
+def panel_label(ax, label: str, *, fontsize: int = 10) -> None:
+    """Bold panel sub-heading with a short dark rule — for faceted charts.
+
+    Renders above the axes::
+
+        --------
+        Economic
+    """
+    fig = ax.get_figure()
+    fig.canvas.draw()
+    bbox = ax.get_position()
+
+    rule_w = 35 / (fig.get_figwidth() * fig.dpi)
+    fig.add_artist(
+        plt.Line2D(
+            [bbox.x0, bbox.x0 + rule_w],
+            [bbox.y1 + 0.052, bbox.y1 + 0.052],
+            transform=fig.transFigure,
+            color=C_SPINE,
+            linewidth=1.2,
+            solid_capstyle="butt",
+            clip_on=False,
+        )
+    )
+    fig.text(
+        bbox.x0,
+        bbox.y1 + 0.010,
+        label,
+        transform=fig.transFigure,
+        fontsize=fontsize,
+        fontweight="bold",
+        color=C_TEXT,
+        va="bottom",
+        ha="left",
+    )

graphs/_fonts.py

@@ -0,0 +1,66 @@
+"""IBM Plex Sans font management for matplotlib.
+
+Downloads font files from github.com/IBM/plex only when the font
+is not already registered in matplotlib's font manager.
+"""
+
+import logging
+import os
+import urllib.request
+
+import matplotlib.font_manager as fm
+
+_log = logging.getLogger(__name__)
+
+_IBM_BASE = (
+    "https://github.com/IBM/plex/raw/master/"
+    "packages/plex-sans/fonts/complete/ttf/"
+)
+_IBM_FILES = [
+    "IBMPlexSans-Regular.ttf",
+    "IBMPlexSans-Bold.ttf",
+    "IBMPlexSans-SemiBold.ttf",
+    "IBMPlexSans-Light.ttf",
+    "IBMPlexSans-Italic.ttf",
+]
+_FONT_NAME = "IBM Plex Sans"
+_FALLBACK = "DejaVu Sans"
+
+
+def _is_registered() -> bool:
+    """Check if IBM Plex Sans is already in matplotlib's font manager."""
+    return any(f.name == _FONT_NAME for f in fm.fontManager.ttflist)
+
+
+def ensure_ibm_plex() -> str:
+    """Return the font family name, downloading only if not already available."""
+    if _is_registered():
+        return _FONT_NAME
+
+    font_dir = os.path.join(os.path.dirname(__file__), "_fonts_cache")
+    os.makedirs(font_dir, exist_ok=True)
+
+    for fname in _IBM_FILES:
+        path = os.path.join(font_dir, fname)
+        if not os.path.exists(path):
+            try:
+                urllib.request.urlretrieve(_IBM_BASE + fname, path)
+            except Exception:
+                _log.debug("Failed to download %s", fname, exc_info=True)
+                continue
+        try:
+            fm.fontManager.addfont(path)
+        except Exception:
+            _log.debug("Failed to register font %s", fname, exc_info=True)
+
+    return _FONT_NAME if _is_registered() else _FALLBACK
+
+
+FONT: str = ""
+
+
+def _get_font() -> str:
+    global FONT  # noqa: PLW0603
+    if not FONT:
+        FONT = ensure_ibm_plex()
+    return FONT

graphs/_labels.py

@@ -0,0 +1,197 @@
+"""Direct line labelling — replaces legends for line charts."""
+
+from __future__ import annotations
+
+import warnings
+from collections import defaultdict
+
+import matplotlib.patheffects as pe
+
+from graphs._palette import C_BG
+
+
+def label_lines(
+    ax,
+    labels: list[str] | None = None,
+    *,
+    x_offset: int = 6,
+    fontsize: int = 9,
+    stroke: bool = True,
+    min_sep_pct: float = 5.0,
+    tick_pad_pct: float = 4.5,
+    edge_pull_pct: float = 1.5,
+):
+    """Label each line at its rightmost point instead of using a legend.
+
+    Visible y-tick rows are treated as fixed dividers. Each label is placed
+    in the band between two consecutive ticks (with `tick_pad_pct` padding off
+    each tick) so labels can never obscure axis tick text. Within a band,
+    labels are spread evenly with at least `min_sep_pct` separation; if the
+    band is too narrow for the labels in it, separation shrinks to fit
+    without spilling onto the tick rows.
+
+    Args:
+        labels: Override list of strings (defaults to line labels).
+        x_offset: Horizontal pixel offset from the last data point.
+        fontsize: Label font size.
+        stroke: White halo behind text to avoid clashing with gridlines.
+        min_sep_pct: Minimum label separation as % of y-axis range.
+        tick_pad_pct: Minimum gap between any label and a y-tick row,
+            as % of y-axis range. Set to 0 to disable tick-avoidance.
+        edge_pull_pct: When a line ends exactly at y_lo or y_hi (so its
+            label would otherwise sit on top of the 0% / 100% tick text),
+            pull the label this many % of the y-range *into* the chart.
+            Set to 0 to disable.
+    """
+    lines = [line for line in ax.get_lines() if not line.get_label().startswith("_")]
+    if not lines:
+        return
+
+    y_lo, y_hi = ax.get_ylim()
+    span = y_hi - y_lo
+    min_sep = span * min_sep_pct / 100
+    tick_pad = span * tick_pad_pct / 100
+    edge_pull = span * edge_pull_pct / 100
+
+    # Visible ticks define band boundaries. The axis limits cap the outer bands.
+    yticks = sorted(t for t in ax.get_yticks() if y_lo <= t <= y_hi)
+    tick_set = set(yticks)
+    edges = [y_lo] + yticks + [y_hi]
+    bands: list[tuple[float, float]] = []
+    for i in range(len(edges) - 1):
+        lo = edges[i] + (tick_pad if edges[i] in tick_set else 0)
+        hi = edges[i + 1] - (tick_pad if edges[i + 1] in tick_set else 0)
+        if hi > lo:
+            bands.append((lo, hi))
+    if not bands:  # degenerate: no usable band, fall back to full axis
+        bands = [(y_lo, y_hi)]
+
+    chart_center = (y_lo + y_hi) / 2
+
+    def assign_band(y: float) -> tuple[float, float]:
+        """Pick the band for a label at `y`.
+
+        Strict containment wins. Otherwise pick the band whose nearest edge
+        is closest to `y`; on ties (label sits exactly on a tick boundary),
+        pick the band whose centre is closer to the chart centre — so labels
+        for lines that end at the axis extremes land *interior* to the chart
+        rather than spilling outside the spine.
+        """
+        for lo, hi in bands:
+            if lo <= y <= hi:
+                return (lo, hi)
+
+        def edge_dist(b):
+            lo, hi = b
+            return min(abs(lo - y), abs(hi - y))
+
+        d_min = min(edge_dist(b) for b in bands)
+        candidates = [b for b in bands if edge_dist(b) == d_min]
+        if len(candidates) == 1:
+            return candidates[0]
+        return min(candidates, key=lambda b: abs((b[0] + b[1]) / 2 - chart_center))
+
+    items: list[list] = []
+    for i, line in enumerate(lines):
+        lbl = labels[i] if labels and i < len(labels) else line.get_label()
+        y = float(line.get_ydata()[-1])
+        # Pull labels that hug the axis extremes into the chart so they don't
+        # collide with the 0% / 100% tick text.
+        if edge_pull > 0:
+            if abs(y - y_hi) < tick_pad:
+                y = y_hi - edge_pull - tick_pad
+            elif abs(y - y_lo) < tick_pad:
+                y = y_lo + edge_pull + tick_pad
+        items.append([y, lbl, line, assign_band(y)])
+
+    # Distribute each band's labels evenly inside it, anchored near their mean y.
+    by_band: dict[tuple[float, float], list[list]] = defaultdict(list)
+    for it in items:
+        by_band[it[3]].append(it)
+
+    for (band_lo, band_hi), group in by_band.items():
+        group.sort(key=lambda it: it[0])
+        n = len(group)
+        if n == 1:
+            group[0][0] = max(band_lo, min(band_hi, group[0][0]))
+            continue
+        avail = band_hi - band_lo
+        sep = min(min_sep, avail / (n - 1))
+        total = (n - 1) * sep
+        mean_y = sum(it[0] for it in group) / n
+        center = max(band_lo + total / 2, min(band_hi - total / 2, mean_y))
+        start = center - total / 2
+        for i, it in enumerate(group):
+            it[0] = start + i * sep
+
+    path_fx = [pe.withStroke(linewidth=3, foreground=C_BG)] if stroke else []
+    annotations = []
+    for nudged_y, lbl, line, _ in items:
+        ann = ax.annotate(
+            lbl,
+            xy=(line.get_xdata()[-1], nudged_y),
+            xytext=(x_offset, 0),
+            textcoords="offset points",
+            va="center",
+            fontsize=fontsize,
+            color=line.get_color(),
+            path_effects=path_fx,
+            clip_on=False,
+            annotation_clip=False,
+        )
+        annotations.append(ann)
+
+    # Render-pass: detect residual overlaps between labels in pixel space and
+    # spread them in y. Necessary because the band-distribution pass works in
+    # data coords and can leave labels touching when the band is very thin or
+    # when two lines end within a few pixels of each other.
+    fig = ax.get_figure()
+    try:
+        fig.canvas.draw()
+        renderer = fig.canvas.get_renderer()
+    except Exception:
+        return
+
+    def _bbox(a):
+        return a.get_window_extent(renderer=renderer)
+
+    for _ in range(8):
+        bboxes = [(_bbox(a), a) for a in annotations]
+        bboxes.sort(key=lambda b: b[0].y0)
+        moved = False
+        for i in range(1, len(bboxes)):
+            prev_bb, _ = bboxes[i - 1]
+            cur_bb, cur_ann = bboxes[i]
+            overlap = prev_bb.y1 - cur_bb.y0
+            if overlap > 0:
+                # nudge current annotation up by `overlap + 1px`
+                shift_px = overlap + 1
+                inv = ax.transData.inverted()
+                _, y0 = inv.transform((0, 0))
+                _, y1 = inv.transform((0, shift_px))
+                dy = y1 - y0
+                xy = cur_ann.xy
+                cur_ann.xy = (xy[0], xy[1] + dy)
+                moved = True
+        if not moved:
+            break
+
+    # Final warning if any label still overlaps a y-tick label in pixel space.
+    tick_bboxes = []
+    for tl in ax.get_yticklabels():
+        if tl.get_text():
+            try:
+                tick_bboxes.append(tl.get_window_extent(renderer=renderer))
+            except Exception:
+                pass
+    for ann in annotations:
+        bb = _bbox(ann)
+        for tb in tick_bboxes:
+            if bb.overlaps(tb):
+                warnings.warn(
+                    f"graphs.label_lines: label {ann.get_text()!r} overlaps "
+                    "a y-tick label. Consider increasing tick_pad_pct or "
+                    "tightening y-limits.",
+                    stacklevel=2,
+                )
+                break

graphs/_legend.py

@@ -0,0 +1,145 @@
+"""Smart legend placement — pick the emptiest corner of the axes."""
+
+from __future__ import annotations
+
+import warnings
+
+from graphs._palette import C_BG, C_SPINE
+
+
+_CORNERS = {
+    "upper right": (1, 1),
+    "upper left": (0, 1),
+    "lower right": (1, 0),
+    "lower left": (0, 0),
+}
+
+
+def smart_legend(
+    ax,
+    *,
+    pad: float = 0.02,
+    prefer: tuple[str, ...] = ("upper right", "upper left", "lower right", "lower left"),
+    fontsize: int = 9,
+    frame: bool = True,
+    **legend_kwargs,
+):
+    """Place a legend in the emptiest corner of the axes.
+
+    Inspects every artist on `ax` (lines, bars, error-bars, scatter, fills),
+    samples their occupied pixel bboxes, and picks the corner of the axes that
+    has the most empty space for a legend roughly sized to fit the entries.
+
+    Args:
+        pad: Fractional inset from the axes edge (data area).
+        prefer: Tie-break order among equally-empty corners.
+        fontsize: Legend text size.
+        frame: Draw a thin frame matching the spine colour. Set False for
+            frameless legends.
+        **legend_kwargs: Forwarded to ax.legend (e.g. title, ncol).
+
+    Returns:
+        The matplotlib Legend object.
+    """
+    fig = ax.get_figure()
+    try:
+        fig.canvas.draw()
+        renderer = fig.canvas.get_renderer()
+    except Exception:
+        return ax.legend(loc=prefer[0], fontsize=fontsize, **legend_kwargs)
+
+    handles, labels = ax.get_legend_handles_labels()
+    if not handles:
+        return None
+
+    # Draft legend off-axes to measure its size.
+    draft = ax.legend(
+        handles,
+        labels,
+        loc="upper right",
+        fontsize=fontsize,
+        frameon=frame,
+        **legend_kwargs,
+    )
+    fig.canvas.draw()
+    leg_bbox_px = draft.get_window_extent(renderer=renderer)
+    leg_w_px = leg_bbox_px.width
+    leg_h_px = leg_bbox_px.height
+    draft.remove()
+
+    ax_bbox = ax.get_window_extent(renderer=renderer)
+
+    # Gather artist bboxes that count as "data ink" we should avoid.
+    artist_bboxes = []
+    for art in (
+        list(ax.lines)
+        + list(ax.patches)
+        + list(ax.collections)
+        + list(ax.containers)
+    ):
+        # ErrorbarContainer / BarContainer aren't artists themselves but iterate.
+        if hasattr(art, "get_window_extent"):
+            try:
+                bb = art.get_window_extent(renderer=renderer)
+                if bb.width > 0 and bb.height > 0:
+                    artist_bboxes.append(bb)
+            except Exception:
+                pass
+        elif hasattr(art, "__iter__"):
+            for sub in art:
+                try:
+                    bb = sub.get_window_extent(renderer=renderer)
+                    if bb.width > 0 and bb.height > 0:
+                        artist_bboxes.append(bb)
+                except Exception:
+                    pass
+
+    def overlap_score(corner: str) -> float:
+        ax_x, ax_y = _CORNERS[corner]
+        # Pixel box for the candidate legend at this corner.
+        if ax_x == 1:
+            x1 = ax_bbox.x1 - pad * ax_bbox.width
+            x0 = x1 - leg_w_px
+        else:
+            x0 = ax_bbox.x0 + pad * ax_bbox.width
+            x1 = x0 + leg_w_px
+        if ax_y == 1:
+            y1 = ax_bbox.y1 - pad * ax_bbox.height
+            y0 = y1 - leg_h_px
+        else:
+            y0 = ax_bbox.y0 + pad * ax_bbox.height
+            y1 = y0 + leg_h_px
+
+        score = 0.0
+        for bb in artist_bboxes:
+            ox = max(0, min(x1, bb.x1) - max(x0, bb.x0))
+            oy = max(0, min(y1, bb.y1) - max(y0, bb.y0))
+            score += ox * oy
+        return score
+
+    scored = [(overlap_score(c), prefer.index(c), c) for c in prefer]
+    scored.sort()  # lowest overlap wins; tie-break by user preference order
+    best = scored[0][2]
+    if scored[0][0] > 0:
+        warnings.warn(
+            f"graphs.smart_legend: best corner {best!r} still overlaps "
+            "data. Consider tightening axes limits or moving the legend "
+            "outside the axes with bbox_to_anchor.",
+            stacklevel=2,
+        )
+
+    leg = ax.legend(
+        handles,
+        labels,
+        loc=best,
+        fontsize=fontsize,
+        frameon=frame,
+        **legend_kwargs,
+    )
+    if frame:
+        frame_obj = leg.get_frame()
+        frame_obj.set_edgecolor(C_SPINE)
+        frame_obj.set_linewidth(0.5)
+        frame_obj.set_facecolor(C_BG)
+        frame_obj.set_alpha(0.92)
+    return leg

graphs/_palette.py

@@ -0,0 +1,22 @@
+"""Economist-style colour palette and visual constants."""
+
+# Background and structural colours
+C_BG = "#FFFFFF"
+C_SPINE = "#1A1A1A"
+C_GRID = "#D9D9D9"
+C_TEXT = "#1A1A1A"
+C_LABEL = "#666666"
+C_RED = "#bf352b"
+C_CI = "#f5c5b8"
+
+# Categorical colour cycle — red is the primary accent
+colors = [
+    "#bf352b",  # Red   — primary
+    "#006BA2",  # Blue
+    "#3EBCD2",  # Teal
+    "#379A8B",  # Green
+    "#EBB434",  # Yellow
+    "#9A607F",  # Mauve
+    "#758D99",  # Slate
+    "#DB444B",  # Coral
+]

graphs/_theme.py

@@ -0,0 +1,70 @@
+"""Economist-style matplotlib/seaborn global theme."""
+
+import matplotlib.pyplot as plt
+
+from graphs._fonts import _get_font
+from graphs._palette import (
+    C_BG,
+    C_GRID,
+    C_LABEL,
+    C_SPINE,
+    C_TEXT,
+    colors,
+)
+
+
+def set_theme() -> None:
+    """Apply The Economist's visual style globally to matplotlib/seaborn."""
+    plt.rcParams.update(
+        {
+            # Figure
+            "figure.facecolor": C_BG,
+            "figure.dpi": 150,
+            "figure.figsize": (7, 5),
+            # Axes
+            "axes.facecolor": C_BG,
+            "axes.edgecolor": C_SPINE,
+            "axes.linewidth": 1.0,
+            "axes.spines.top": False,
+            "axes.spines.right": False,
+            "axes.spines.left": False,
+            "axes.spines.bottom": True,
+            "axes.grid": True,
+            "axes.grid.axis": "y",
+            "axes.axisbelow": True,
+            "axes.labelcolor": C_LABEL,
+            "axes.labelsize": 9,
+            "axes.labelpad": 4,
+            "axes.prop_cycle": plt.cycler("color", colors),
+            # Grid
+            "grid.color": C_GRID,
+            "grid.linewidth": 0.6,
+            "grid.linestyle": "-",
+            # Ticks
+            "xtick.color": C_SPINE,
+            "ytick.color": C_LABEL,
+            "xtick.labelcolor": C_LABEL,
+            "ytick.labelcolor": C_LABEL,
+            "xtick.labelsize": 9,
+            "ytick.labelsize": 9,
+            "xtick.major.size": 3.5,
+            "xtick.major.width": 0.8,
+            "ytick.major.size": 0,
+            "xtick.minor.size": 0,
+            "ytick.minor.size": 0,
+            "xtick.bottom": True,
+            "xtick.direction": "out",
+            # Typography
+            "font.family": "sans-serif",
+            "font.sans-serif": [_get_font(), "Verdana", "Arial", "DejaVu Sans"],
+            "text.color": C_TEXT,
+            # Legend
+            "legend.frameon": False,
+            "legend.fontsize": 8.5,
+            "legend.labelcolor": C_TEXT,
+            # Lines & patches
+            "lines.linewidth": 2.0,
+            "lines.solid_capstyle": "round",
+            "patch.edgecolor": "none",
+        }
+    )