fluxplot 0.1.0__py3-none-any.whl

fluxplot/stats/two_group.py

@@ -0,0 +1,149 @@
+"""Tests for two independent (unpaired) samples.
+
+Each function returns one row as a dict keyed by :data:`REPORT_COLUMNS`, so a set of comparisons
+drops straight into a DataFrame (``pl.DataFrame([fp.stats.welch_hedges(a, b)])``) and from there
+into a plot's ``_stats`` dissection as a CSV.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Tuple
+
+import numpy as np
+from scipy import optimize as _opt
+from scipy import stats as _sp
+
+from ._common import REPORT_COLUMNS, as_sample, check_alternative, report_row
+
+__all__ = ["welch_hedges", "mann_whitney_cliff", "REPORT_COLUMNS"]
+
+_Z = _sp.norm.ppf(0.975)
+
+
+def hedges_unpooled(a: np.ndarray, b: np.ndarray) -> Tuple[float, float, float]:
+    """Hedges' g standardised by the non-pooled SD ``sqrt((var_a + var_b) / 2)`` with its Bonett
+    (2008) 95% CI: ``(g, lo, hi)``. Shared by :func:`welch_hedges` and the Games–Howell post hoc."""
+    n1, n2 = a.size, b.size
+    v1, v2 = a.var(ddof=1), b.var(ddof=1)
+    s = np.sqrt((v1 + v2) / 2)
+    if s == 0:
+        raise ValueError("both samples have zero variance; the effect size is undefined")
+    d = (a.mean() - b.mean()) / s
+    j = 1 - 3 / (4 * (n1 + n2 - 2) - 1)
+    se = np.sqrt(d**2 * (v1**2 / (n1 - 1) + v2**2 / (n2 - 1)) / (8 * s**4)
+                 + (v1 / (n1 - 1) + v2 / (n2 - 1)) / s**2)
+    return float(j * d), float(d - _Z * se), float(d + _Z * se)
+
+
+def cliffs_delta(a: np.ndarray, b: np.ndarray) -> Tuple[float, float, float]:
+    """Cliff's delta ``P(a > b) - P(a < b)`` with Newcombe's Method 5 95% CI: ``(delta, lo, hi)``.
+    Shared by :func:`mann_whitney_cliff` and Dunn's post hoc."""
+    delta = float(np.sign(a[:, None] - b[None, :]).mean())  # mean of sign(a_i - b_j) over all pairs
+    lo, hi = _newcombe_auc_bounds((delta + 1) / 2, a.size, b.size)
+    return delta, 2 * lo - 1, 2 * hi - 1
+
+
+def welch_hedges(a: Any, b: Any, *, alternative: str = "two-sided", names=("a", "b")) -> Dict[str, Any]:
+    """Welch's t-test of ``a`` vs ``b`` with Hedges' g (non-pooled SD) and its 95% CI.
+
+    For independent samples compared on their arithmetic means. The effect size is standardized by
+    the non-pooled SD ``sqrt((var_a + var_b) / 2)``, so it stays meaningful when the group variances
+    differ. The estimate carries the small-sample bias correction
+    ``J = 1 - 3 / (4 (n_a + n_b - 2) - 1)``. The 95% CI is Bonett's (2008) unequal-variance interval
+    for the population value; it is not multiplied by ``J``, because the interval targets the
+    parameter itself and ``J`` would pull it off target (simulated coverage is 95–97% as is).
+
+    Signs follow ``a - b``: a positive statistic and effect size mean ``a`` has the larger mean.
+
+    Parameters
+    ----------
+    a, b
+        The two samples (any 1-D array-like of numbers). Each needs at least 2 finite values.
+    alternative
+        ``"two-sided"`` (default), ``"less"`` (``a`` has the smaller mean) or ``"greater"``. The
+        p-value follows it; the effect-size CI is always the two-sided 95% interval.
+    names
+        The names of the two groups, recorded in the row's ``groups`` (``("a", "b")`` by default).
+
+    Returns
+    -------
+    dict
+        One reporting row keyed by :data:`REPORT_COLUMNS`: the test name, the t statistic, the
+        p-value, the Welch–Satterthwaite degrees of freedom, the effect-size method, its value and
+        its 95% CI formatted as ``"[low, high]"`` (2 decimals) and as numbers, the sample sizes,
+        the group names and the alternative.
+
+    Example
+    -------
+    >>> row = fp.stats.welch_hedges(sd_values, sleep_values, names=("SD", "sleep"))
+    >>> pl.DataFrame([row]).write_csv("plots/_dissections/app/_stats/welch_ttest.csv")
+    """
+    a = as_sample(a, "a")
+    b = as_sample(b, "b")
+    g, lo, hi = hedges_unpooled(a, b)
+    t = _sp.ttest_ind(a, b, equal_var=False, alternative=check_alternative(alternative))
+    return report_row("Welch's t-test", t.statistic, t.pvalue, t.df, "Hedges' g (non-pooled SD)",
+                      g, lo, hi, n=(a.size, b.size), groups=names, alternative=alternative)
+
+
+def _newcombe_auc_bounds(theta: float, m: int, n: int) -> Tuple[float, float]:
+    """Newcombe's (2006) Method 5 95% interval for ``theta = P(a > b) + P(a = b) / 2``.
+
+    A score-type interval: the bounds are the ``t`` solving ``(t - theta)^2 = z^2 V(t)``, where
+    ``V`` is the Hanley–McNeil variance of the Mann–Whitney estimate with both sample sizes
+    replaced by ``N* = (m + n) / 2 - 1``. Unlike a Wald interval it stays inside ``[0, 1]`` and
+    does not collapse when the groups do not overlap (``theta`` = 0 or 1).
+    """
+    n_star = (m + n) / 2 - 1
+
+    def gap(t: float) -> float:
+        var = t * (1 - t) * (1 + (n_star - 1) * ((1 - t) / (2 - t) + t / (1 + t))) / (m * n)
+        return (t - theta) ** 2 - _Z**2 * var
+
+    # gap(0) = theta^2 > 0 and gap(1) = (1 - theta)^2 > 0 while gap(theta) < 0, so each bound is
+    # the one root on its side; at theta = 0 or 1 the bound on that side is the boundary itself
+    # (gap vanishes there), so search just inside it.
+    eps = 1e-12
+    lo = 0.0 if theta <= 0 else _opt.brentq(gap, 0.0, min(theta, 1 - eps), xtol=1e-14)
+    hi = 1.0 if theta >= 1 else _opt.brentq(gap, max(theta, eps), 1.0, xtol=1e-14)
+    return lo, hi
+
+
+def mann_whitney_cliff(a: Any, b: Any, *, alternative: str = "two-sided", names=("a", "b")) -> Dict[str, Any]:
+    """Mann–Whitney U test of ``a`` vs ``b`` with Cliff's delta and its 95% CI.
+
+    For independent samples compared by rank (ordered categories, or a rank-based comparison chosen
+    before looking at the results). The p-value is scipy's two-sided ``mannwhitneyu``
+    (``method="auto"``: exact for small samples without ties, otherwise the normal approximation
+    with tie and continuity corrections).
+
+    Cliff's delta is ``P(a > b) - P(a < b)`` over all ``n_a * n_b`` cross-group pairs (ties count
+    as neither), which equals ``2 U_a / (n_a n_b) - 1``. Its 95% CI is Newcombe's (2006) Method 5
+    score interval for ``theta = (delta + 1) / 2``, mapped back to the delta scale. It stays inside
+    ``[-1, 1]`` and, unlike Cliff's own (1996) interval, does not collapse to a point when the
+    groups do not overlap at all (``delta = ±1``) — common with small samples.
+
+    Signs follow ``a - b``: a positive delta means values in ``a`` tend to be larger.
+
+    Parameters
+    ----------
+    a, b
+        The two samples (any 1-D array-like of numbers). Each needs at least 2 finite values.
+    alternative
+        ``"two-sided"`` (default), ``"less"`` or ``"greater"`` (the direction of ``a`` relative to
+        ``b``). The CI is always two-sided.
+    names
+        The names of the two groups, recorded in the row's ``groups``.
+
+    Returns
+    -------
+    dict
+        One reporting row keyed by :data:`REPORT_COLUMNS`. The statistic is ``U`` for ``a`` (the
+        number of pairs with ``a > b``, ties counting one half); ``dof`` is ``None`` (a rank test
+        has no degrees of freedom).
+    """
+    a = as_sample(a, "a")
+    b = as_sample(b, "b")
+    u = _sp.mannwhitneyu(a, b, alternative=check_alternative(alternative), method="auto")
+    delta, lo, hi = cliffs_delta(a, b)
+    return report_row("Mann–Whitney U test", u.statistic, u.pvalue, None, "Cliff's delta", delta,
+                      lo, hi, n=(a.size, b.size), groups=names, alternative=alternative)

fluxplot/style.py

@@ -0,0 +1,469 @@
+"""fluxplot.style — a consistent, beautiful matplotlib house style (Flexoki + cmasher).
+
+A thin, additive theming layer, in the same spirit as the rest of FluxPlot: you keep plotting in
+ordinary matplotlib, and this gives every plot a coherent visual identity. It is **independent of
+the semantic API** — use it for quick exploratory plots (``plt.plot``) just as happily as for the
+publication figures you ``fp.save``. One import, and everything you make looks like it belongs to
+the same set.
+
+    from fluxplot import style as fx
+    fx.use_light()                      # apply the theme (call before creating figures)
+
+    import matplotlib.pyplot as plt
+    fig, ax = plt.subplots()
+    ax.plot(x, y)                       # picks up the Flexoki color cycle automatically
+    fx.despine(ax); fx.title(ax, "My result", "a short subtitle")
+
+What you get:
+- the **Flexoki** palette (Steph Ango, https://stephango.com/flexoki) as :data:`FLEXOKI`, plus
+  light/dark categorical cycles installed as matplotlib's ``prop_cycle``;
+- perceptually-uniform **continuous colormaps** (:data:`SEQUENTIAL`, :data:`DIVERGING`, …) from
+  the shipped cmasher collection, installed as matplotlib's default ``image.cmap`` so every
+  ``imshow`` / ``fp.heatmap`` without ``cmap=`` uses the house map;
+- :func:`use_light` / :func:`use_dark` themes (clean, despined, sensible fonts/DPI);
+- small helpers :func:`despine` and :func:`title`.
+
+Notes
+-----
+- **Backend-agnostic:** this module never calls ``matplotlib.use(...)``, so it won't fight your
+  notebook/interactive backend. For headless scripts set ``MPLBACKEND=Agg`` (or call
+  ``matplotlib.use("Agg")``) yourself before importing pyplot.
+- **It's yours to tune:** the rcParams live here, but every color definition comes from
+  :mod:`fluxplot.colors` — the canonical palette/colormap module. Edit hexes *there* and every
+  future plot (and this theme) follows.
+"""
+
+from __future__ import annotations
+
+import matplotlib as mpl
+
+from .colors import flex as _flex
+from .colors import maps as _maps
+
+__all__ = [
+    "CYCLE_DARK",
+    "CYCLE_LIGHT",
+    "CYCLE_ORDER",
+    "CYCLIC",
+    "DEFAULT_DIVERGING",
+    "DIVERGING",
+    "FLEXOKI",
+    "FLEXOKI_DIVERGING",
+    "FLEXOKI_SEQUENTIAL",
+    "FLEXOKI_WARM",
+    "HAVE_CMASHER",
+    "SEQUENTIAL",
+    "SEQUENTIAL_WARM",
+    "SPECTRUM",
+    "TERRAIN",
+    "despine",
+    "title",
+    "use_dark",
+    "use_light",
+    "use_lighttable",
+    "use_paper",
+    "ACTIVE",
+    "THEMES",
+    "TOKEN_RCPARAMS",
+    "current_tokens",
+    "theme_record",
+]
+
+# ---------------------------------------------------------------------------
+# Flexoki palette (https://stephango.com/flexoki), built from the canonical
+# definitions in fluxplot.colors. 600-weight accents read well on the light
+# "paper" background; 400-weight ("*2") on dark. Retune in fluxplot.colors.
+# ---------------------------------------------------------------------------
+_BASE_LEVELS = (50, 100, 150, 200, 300, 400, 500, 600, 700, 800, 850, 900, 950)
+_ACCENTS = (
+    "red",
+    "orange",
+    "yellow",
+    "olive",
+    "green",
+    "cyan",
+    "blue",
+    "purple",
+    "magenta",
+)
+
+FLEXOKI = {"paper": _flex.paper, "black": _flex.black}
+for _lvl in _BASE_LEVELS:
+    FLEXOKI[f"base{_lvl}"] = _flex.get(f"base-{_lvl}")["hex"]
+for _name in _ACCENTS:
+    FLEXOKI[_name] = _flex.get(f"{_name}-600")["hex"]  # primary, for light backgrounds
+    FLEXOKI[f"{_name}2"] = _flex.get(f"{_name}-400")[
+        "hex"
+    ]  # lighter, for dark backgrounds
+
+# Categorical cycles — a distinct, harmonious hue order. The active theme installs
+# one as matplotlib's prop_cycle, so un-coloured series are assigned from it.
+# The order keeps every ADJACENT pair apart for colour-deficient readers: measured with
+# fluxplot.colorcheck (Machado 2009, CIEDE2000), the smallest adjacent distance under
+# protanopia / deuteranopia / tritanopia is 20.4 in the light cycle and 15.4 in the dark one
+# (the pre-2026-09-30 order had cyan next to magenta at 5.6 and orange next to green at 7.8).
+# Greyscale separation cannot be fixed by ordering alone at one weight; a print-safe figure
+# should still vary marker or line style. tests/test_colorcheck.py pins the adjacency.
+CYCLE_ORDER = ("blue", "orange", "purple", "green", "magenta", "yellow", "cyan", "red")
+CYCLE_LIGHT = [FLEXOKI[c] for c in CYCLE_ORDER]
+CYCLE_DARK = [FLEXOKI[c + "2"] for c in CYCLE_ORDER]
+
+
+# ---------------------------------------------------------------------------
+# Continuous colormaps. The defaults are cmasher's perceptually-uniform maps (the
+# scientifically honest choice for continuous data). The Flexoki maps — defined in
+# fluxplot.colors, addressable by name (cmap="flexoki_diverging") — are linear ramps
+# through palette anchors, pleasant but not perceptually uniform; e.g.
+# FLEXOKI_DIVERGING is light-centred (blue–paper–red), handy for correlation matrices.
+# ---------------------------------------------------------------------------
+FLEXOKI_SEQUENTIAL = _maps.flexoki_sequential
+FLEXOKI_WARM = _maps.flexoki_warm
+FLEXOKI_DIVERGING = _maps.flexoki_diverging
+TERRAIN = _maps.flexoki_terrain
+SPECTRUM = _maps.flexoki_spectrum
+
+# The perceptually-uniform house maps, from fluxplot's shipped cmasher definitions (the JSON
+# collection in fluxplot.colors, so no package import at runtime and the very same colours Flux's
+# picker shows). Tweak these picks to taste — any shipped map works (fx.maps.<name>):
+#   sequential: rainforest, ember, amber, gem, ocean, dusk, eclipse, …
+#   diverging:  fusion, iceburn, redshift, wildfire, pride, …
+#   cyclic:     infinity, emergence
+HAVE_CMASHER = True  # kept for callers that checked it; cmasher is a dependency
+SEQUENTIAL = _maps.get("cmasher.rainforest")
+SEQUENTIAL_WARM = _maps.get("cmasher.ember")
+DIVERGING = _maps.get("cmasher.fusion")
+CYCLIC = _maps.get("cmasher.infinity")
+
+#: Name of the default diverging map — what helpers with ``center=`` use when no cmap is given.
+DEFAULT_DIVERGING = DIVERGING.name
+
+# Typography. We set the generic family + a fallback chain rather than a single
+# face, so a missing font degrades silently to a sane default (no per-figure
+# warnings). Arial (sans) / Georgia (serif) are used if present.
+SANS_STACK = ["Arial", "Helvetica", "Lato", "Helvetica Neue", "DejaVu Sans"]
+SERIF_STACK = [
+    "Georgia",
+    "Times New Roman",
+    "Latin Modern Roman",
+    "CMU Serif",
+    "DejaVu Serif",
+]
+
+
+def _title_weight(serif: bool) -> str:
+    """The heaviest honest title weight: ``"medium"`` only when the family
+    matplotlib will actually resolve (the first installed face in the stack)
+    ships a 500 weight — otherwise ``"normal"``. Requesting an absent weight
+    made findfont print ``Failed to find font weight medium, now using 400.``
+    once per process (noise that buried real failures in long batch runs)
+    while rendering the exact same 400 anyway."""
+    from matplotlib import font_manager as _fm
+
+    stack = SERIF_STACK if serif else SANS_STACK
+    available: dict[str, set] = {}
+    for f in _fm.fontManager.ttflist:
+        available.setdefault(f.name.lower(), set()).add(f.weight)
+    for fam in stack:
+        weights = available.get(fam.lower())
+        if weights is None:
+            continue
+        has_medium = any(
+            w == "medium" or (isinstance(w, (int, float)) and 450 <= w <= 550)
+            for w in weights
+        )
+        return "medium" if has_medium else "normal"
+    return "normal"
+
+
+def _base_rc(ink, muted, grid, paper, serif):
+    return {
+        "axes.spines.top": False,
+        "axes.spines.right": False,
+        "font.family": "serif" if serif else "sans-serif",
+        "font.sans-serif": SANS_STACK,
+        "font.serif": SERIF_STACK,
+        "font.size": 6,  # 6pt as default
+        "axes.titlesize": 6,  # 6pt font for axes titles
+        "axes.titleweight": _title_weight(serif),
+        "axes.titlepad": 12,
+        "axes.labelsize": 6,  # 6pt font for axes labels
+        "axes.labelpad": 6,
+        "axes.labelcolor": ink,
+        "text.color": ink,
+        "axes.edgecolor": muted,
+        "axes.linewidth": 1.2,  # 1.2 default linewidth for axes
+        "axes.facecolor": paper,
+        "figure.facecolor": paper,
+        "savefig.facecolor": paper,
+        "axes.grid": grid,
+        "axes.axisbelow": True,
+        "grid.color": FLEXOKI["base150"],
+        "grid.linewidth": 0.8,
+        "grid.alpha": 0.9,
+        "xtick.color": muted,
+        "ytick.color": muted,
+        "xtick.labelcolor": ink,
+        "ytick.labelcolor": ink,
+        "xtick.labelsize": 5,
+        "ytick.labelsize": 5,
+        "xtick.direction": "out",
+        "ytick.direction": "out",
+        "xtick.major.size": 4.5,
+        "ytick.major.size": 4.5,
+        "xtick.major.width": 1.0,
+        "ytick.major.width": 1.0,
+        "legend.frameon": False,
+        "legend.fontsize": 6,
+        "legend.handlelength": 1.5,
+        "lines.linewidth": 2.0,  # default linewidth
+        "lines.markersize": 6.5,
+        "lines.solid_capstyle": "round",
+        "lines.markeredgewidth": 0.0,
+        "lines.dash_capstyle": "round",
+        "patch.linewidth": 0.0,
+        "figure.figsize": (2, 2),  # default size when figsize isn't given
+        "figure.dpi": 100,
+        "savefig.dpi": 300,
+        "figure.constrained_layout.use": True,
+        "svg.fonttype": "none",  # keep text as text in the SVG (FluxPlot-friendly)
+    }
+
+
+def _exploratory_rc(ink, muted, grid, paper, serif):
+    return {
+        "axes.spines.top": False,
+        "axes.spines.right": False,
+        "font.family": "serif" if serif else "sans-serif",
+        "font.sans-serif": SANS_STACK,
+        "font.serif": SERIF_STACK,
+        "font.size": 12,  # 6pt as default
+        "axes.titlesize": 12,  # 6pt font for axes titles
+        "axes.titleweight": _title_weight(serif),
+        "axes.titlepad": 12,
+        "axes.labelsize": 12,  # 6pt font for axes labels
+        "axes.labelpad": 6,
+        "axes.labelcolor": ink,
+        "text.color": ink,
+        "axes.edgecolor": muted,
+        "axes.linewidth": 1.2,  # 1.2 default linewidth for axes
+        "axes.facecolor": paper,
+        "figure.facecolor": paper,
+        "savefig.facecolor": paper,
+        "axes.grid": grid,
+        "axes.axisbelow": True,
+        "grid.color": FLEXOKI["base150"],
+        "grid.linewidth": 0.8,
+        "grid.alpha": 0.9,
+        "xtick.color": muted,
+        "ytick.color": muted,
+        "xtick.labelcolor": ink,
+        "ytick.labelcolor": ink,
+        "xtick.labelsize": 10,
+        "ytick.labelsize": 10,
+        "xtick.direction": "out",
+        "ytick.direction": "out",
+        "xtick.major.size": 4.5,
+        "ytick.major.size": 4.5,
+        "xtick.major.width": 1.0,
+        "ytick.major.width": 1.0,
+        "legend.frameon": False,
+        "legend.fontsize": 10,
+        "legend.handlelength": 1.5,
+        "lines.linewidth": 2.0,  # default linewidth
+        "lines.markersize": 6.5,
+        "lines.solid_capstyle": "round",
+        "lines.markeredgewidth": 0.0,
+        "lines.dash_capstyle": "round",
+        "patch.linewidth": 0.0,
+        "figure.figsize": (2, 2),  # default size when figsize isn't given
+        "figure.dpi": 100,
+        "savefig.dpi": 300,
+        "figure.constrained_layout.use": True,
+        "svg.fonttype": "none",  # keep text as text in the SVG (FluxPlot-friendly)
+    }
+
+
+# ---------------------------------------------------------------------------
+# The theme record. Every use_* leaves ACTIVE = {"name", "tokens"} behind: the scaffold colours
+# it set, by their role — what fp.save writes as manifest.style and what postprocess tags each
+# scaffold element with (data-ink-fill / data-ink-stroke), so a consumer can restyle a plot's
+# furniture to its own theme (a dark deck) without touching a single data colour.
+# ---------------------------------------------------------------------------
+#: rcParam → token name, in the order ambiguities are resolved (ink first).
+TOKEN_RCPARAMS = (
+    ("ink", "text.color"),
+    ("label", "axes.labelcolor"),
+    ("tick", "xtick.color"),
+    ("axis", "axes.edgecolor"),
+    ("grid", "grid.color"),
+    ("plot", "axes.facecolor"),
+    ("paper", "figure.facecolor"),
+)
+THEMES = ("light", "lighttable", "paper", "dark")
+
+#: The theme in force: ``{"name": "light", "tokens": {"ink": "#100f0f", …}}`` after a use_*.
+ACTIVE: dict | None = None
+
+
+def current_tokens() -> dict:
+    """The scaffold colours matplotlib will draw with right now, by token, as lowercase hex."""
+    from matplotlib.colors import to_hex
+    return {token: to_hex(mpl.rcParams[key]).lower() for token, key in TOKEN_RCPARAMS}
+
+
+def theme_record() -> dict:
+    """``manifest.style``: the tokens as they are at save, and the theme's name when the
+    rcParams still match what that theme set (``None`` once they were changed by hand)."""
+    tokens = current_tokens()
+    name = ACTIVE["name"] if ACTIVE is not None and ACTIVE["tokens"] == tokens else None
+    return {"theme": name, "tokens": tokens}
+
+
+def _record(name: str) -> None:
+    global ACTIVE
+    ACTIVE = {"name": name, "tokens": current_tokens()}
+
+
+def _theme_override() -> str | None:
+    """``recipe.params().__fluxplot__.theme`` — the theme Flux asked a rerun to use instead."""
+    from .recipe import params
+    theme = (params().get("__fluxplot__") or {}).get("theme")
+    if theme is None:
+        return None
+    if theme not in THEMES:
+        raise ValueError(f"__fluxplot__.theme must be one of {', '.join(THEMES)}; got {theme!r}")
+    return theme
+
+
+def _redirected(this: str, serif: bool, grid: bool) -> bool:
+    """Apply the recipe's theme override instead of ``this`` theme; True when it did."""
+    wanted = _theme_override()
+    if wanted is None or wanted == this:
+        return False
+    globals()["use_" + wanted](serif=serif, grid=grid, _override=False)
+    return True
+
+
+def palette_override() -> str | None:
+    """``recipe.params().__fluxplot__.palette`` — the categorical palette Flux asked for."""
+    from .recipe import params
+    spec = (params().get("__fluxplot__") or {}).get("palette")
+    return str(spec) if spec else None
+
+
+def _cycle(default: list) -> list:
+    """The prop cycle a theme installs: the recipe's palette when one is asked for."""
+    from .colors import palette_colors
+    spec = palette_override()
+    return list(palette_colors(spec)) if spec else default
+
+
+def use_light(
+    ink: str = FLEXOKI["black"],
+    muted: str = FLEXOKI["base700"],
+    grid: bool = False,
+    paper: str = "#FFFFFF",  # default needs to be pure white to comply with journals...
+    serif: bool = False,
+    _override: bool = True,
+) -> None:
+    """Apply the paper-background theme (the default look). Call before creating figures."""
+    if _override and _redirected("light", serif, grid):
+        return
+    mpl.rcParams.update(_base_rc(ink, muted, grid, paper, serif))
+    mpl.rcParams["axes.prop_cycle"] = mpl.cycler(color=_cycle(CYCLE_LIGHT))
+    mpl.rcParams["image.cmap"] = SEQUENTIAL.name
+    _record("light")
+
+
+def use_lighttable(
+    ink: str = FLEXOKI["black"],
+    muted: str = FLEXOKI["base700"],
+    grid: bool = False,
+    paper: str = "#FFFFFF",  # default needs to be pure white to comply with journals...
+    serif: bool = False,
+    _override: bool = True,
+) -> None:
+    """Apply the exploratory theme: the light look at screen sizes (12 pt type)."""
+    if _override and _redirected("lighttable", serif, grid):
+        return
+    mpl.rcParams.update(_exploratory_rc(ink, muted, grid, paper, serif))
+    mpl.rcParams["axes.prop_cycle"] = mpl.cycler(color=_cycle(CYCLE_LIGHT))
+    mpl.rcParams["image.cmap"] = SEQUENTIAL.name
+    _record("lighttable")
+
+
+def use_paper(
+    ink: str = FLEXOKI["black"],
+    muted: str = FLEXOKI["base700"],
+    grid: bool = True,
+    paper: str = FLEXOKI["paper"],
+    serif: bool = False,
+    _override: bool = True,
+) -> None:
+    """Apply the warm Flexoki-paper theme (a gridded, cream ground)."""
+    if _override and _redirected("paper", serif, grid):
+        return
+    mpl.rcParams.update(_base_rc(ink, muted, grid, paper, serif))
+    mpl.rcParams["axes.prop_cycle"] = mpl.cycler(color=_cycle(CYCLE_LIGHT))
+    mpl.rcParams["image.cmap"] = SEQUENTIAL.name
+    _record("paper")
+
+
+def use_dark(serif: bool = False, grid: bool = False, bg: str = "#1C1B1A", _override: bool = True) -> None:
+    """Apply the dark theme — for cosmic / nocturnal plots (star maps, attractors)."""
+    if _override and _redirected("dark", serif, grid):
+        return
+    ink, muted = FLEXOKI["base200"], FLEXOKI["base500"]
+    rc = _base_rc(ink, muted, grid, bg, serif)
+    rc.update(
+        {
+            "grid.color": FLEXOKI["base800"],
+            "grid.alpha": 0.6,
+            "xtick.labelcolor": ink,
+            "ytick.labelcolor": ink,
+        }
+    )
+    mpl.rcParams.update(rc)
+    mpl.rcParams["axes.prop_cycle"] = mpl.cycler(color=_cycle(CYCLE_DARK))
+    mpl.rcParams["image.cmap"] = SEQUENTIAL.name
+    _record("dark")
+
+
+# ---------------------------------------------------------------------------
+# small Tufte helpers
+# ---------------------------------------------------------------------------
+def despine(ax, top=True, right=True, left=False, bottom=False) -> None:
+    """Hide chart-junk spines (Tufte-style). Defaults: drop top + right."""
+    for side, off in (
+        ("top", top),
+        ("right", right),
+        ("left", left),
+        ("bottom", bottom),
+    ):
+        ax.spines[side].set_visible(not off)
+
+
+def title(ax, main, sub=None) -> None:
+    """A left-aligned title with an optional muted subtitle line.
+
+    The main title (a left title) is autotagged ``title`` by :func:`fluxplot.save`;
+    the subtitle is tagged ``subtitle`` so it is addressable in the scene graph.
+    """
+    if sub:
+        ax.set_title(f"{main}\n", loc="left")
+        ann = ax.annotate(
+            sub,
+            xy=(0, 1.0),
+            xycoords="axes fraction",
+            xytext=(0, 10),
+            textcoords="offset points",
+            ha="left",
+            va="bottom",
+            fontsize=10.5,
+            color=FLEXOKI["base500"],
+        )
+        from . import api as _api  # lazy: style is imported during api's __init__
+
+        _api.tag(ann, role="subtitle", name="figure", text=sub)
+    else:
+        ax.set_title(main, loc="left")