paperplot-quantum 0.1.0__py3-none-any.whl

paperplot/layout.py

@@ -0,0 +1,133 @@
+"""Figure geometry: width classes, unit conversions, and figsize math.
+
+Pure geometry — no matplotlib styling here. ``units`` live here too (the
+conversions are small and only used for sizing).
+"""
+
+from __future__ import annotations
+
+import difflib
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # avoid a runtime import cycle with journals.py
+    from .journals import JournalSpec
+
+MM_PER_IN = 25.4
+GOLDEN = (1.0 + 5.0 ** 0.5) / 2.0  # ~1.618
+
+
+def mm_to_in(mm: float) -> float:
+    return mm / MM_PER_IN
+
+
+def in_to_mm(inch: float) -> float:
+    return inch * MM_PER_IN
+
+
+def pt_to_mm(pt: float) -> float:
+    return pt * (MM_PER_IN / 72.0)  # 1 pt = 1/72 in
+
+
+class Width(str, Enum):
+    """Standard journal figure widths."""
+
+    SINGLE = "single"
+    ONEHALF = "onehalf"
+    DOUBLE = "double"
+    FULL_PAGE = "full_page"
+
+
+def resolve_width(width) -> str:
+    """Normalize a Width/str to a canonical key, with a friendly error."""
+    if isinstance(width, Width):
+        return width.value
+    key = str(width).strip().lower().replace("-", "_")
+    valid = [w.value for w in Width]
+    if key in valid:
+        return key
+    hint = difflib.get_close_matches(key, valid, n=1)
+    suffix = f" Did you mean {hint[0]!r}?" if hint else ""
+    raise ValueError(f"Unknown width {width!r}. Valid: {valid}.{suffix}")
+
+
+def width_in(spec: "JournalSpec", width="single") -> float:
+    """Physical figure width in inches for the given width class."""
+    key = resolve_width(width)
+    if key == Width.FULL_PAGE.value:
+        key = Width.DOUBLE.value  # full-page spans the double-column block
+    try:
+        return mm_to_in(spec.widths_mm[key])
+    except KeyError:
+        raise ValueError(
+            f"Journal {spec.name!r} has no {key!r} width "
+            f"(has {sorted(spec.widths_mm)})."
+        ) from None
+
+
+def figsize(spec: "JournalSpec", width="single", aspect="golden", height=None):
+    """Return ``(w_in, h_in)``.
+
+    Width is fixed by the column class. Height comes from ``height`` (inches,
+    overrides everything), else ``aspect`` applied to the width, clamped to the
+    page's usable height. ``FULL_PAGE`` defaults to page-height minus the caption
+    reserve so it actually fills the page.
+    """
+    key = resolve_width(width)
+    w = width_in(spec, key)
+    usable_h = mm_to_in(spec.page_height_mm)
+
+    if key == Width.FULL_PAGE.value:
+        if height is not None:
+            h = float(height)
+        else:
+            h = mm_to_in(spec.page_height_mm - spec.caption_reserve_mm)
+        return (w, min(h, usable_h))
+
+    if height is not None:
+        h = float(height)
+    elif aspect in (None, "golden"):
+        h = w / GOLDEN
+    elif aspect == "equal":
+        h = w
+    else:
+        h = w * float(aspect)  # aspect = height / width
+
+    return (w, min(h, usable_h))
+
+import numpy as np
+
+class Row:
+    def __init__(self, name: str, height: float, gap_above: float = 0.0, attached: bool = False):
+        self.name = name
+        self.height = height
+        self.gap_above = gap_above
+        self.attached = attached
+
+class Grid:
+    def __init__(self, *rows: Row, ncols: int = 1, col_width: float = 1.25, wspace: float = 0.3, margins: dict = None):
+        self.rows = list(rows)
+        self.ncols = ncols
+        self.col_width = col_width
+        self.wspace = wspace
+        self.margins = {"left": 0.54, "right": 0.05, "top": 0.18, "bottom": 0.30}
+        if margins:
+            self.margins.update(margins)
+
+class GridAxesDict(dict):
+    """Hybrid array-dict for accessing axes by name or index."""
+    def __init__(self, axes_array, row_names):
+        super().__init__()
+        self.axes_array = axes_array
+        self.row_names = row_names
+        for r_idx, name in enumerate(row_names):
+            for c_idx in range(axes_array.shape[1]):
+                self[(name, c_idx)] = axes_array[r_idx, c_idx]
+                
+    def __getitem__(self, key):
+        if isinstance(key, tuple) and len(key) == 2 and isinstance(key[0], int) and isinstance(key[1], int):
+            return self.axes_array[key[0], key[1]]
+        return super().__getitem__(key)
+    
+    def __iter__(self):
+        return iter(self.axes_array)

paperplot/lint.py

@@ -0,0 +1,156 @@
+"""``preflight()`` — validate a figure against journal rules. Warn, never block.
+
+Returns a structured ``Report`` so CI can gate on it while humans read a table.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Tuple, Union
+
+import matplotlib.colors as mcolors
+
+import importlib
+
+from .journals import JournalSpec
+
+# pp.style() shadows the style submodule on the package; reach it via sys.modules.
+_style = importlib.import_module("paperplot.style")
+
+Number = Union[float, str]
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str          # "warn" | "info"
+    rule: str              # min_font | min_linewidth | gray_luminance
+    locator: str           # human-readable artist location
+    measured: Number
+    limit: Number
+    message: str
+
+
+@dataclass(frozen=True)
+class Report:
+    findings: Tuple[Finding, ...]
+    spec_name: str = ""
+
+    @property
+    def warnings(self) -> Tuple[Finding, ...]:
+        return tuple(f for f in self.findings if f.severity == "warn")
+
+    @property
+    def ok(self) -> bool:
+        return not self.warnings
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+    def by_rule(self, rule: str) -> Tuple[Finding, ...]:
+        return tuple(f for f in self.findings if f.rule == rule)
+
+    def __str__(self) -> str:
+        if not self.findings:
+            return f"preflight [{self.spec_name}]: OK ✓ (no issues)"
+        lines = [f"preflight [{self.spec_name}]: "
+                 f"{len(self.warnings)} warning(s), "
+                 f"{len(self.findings) - len(self.warnings)} info"]
+        for f in self.findings:
+            mark = "⚠" if f.severity == "warn" else "ℹ"
+            lines.append(f"  {mark} {f.message}")
+        return "\n".join(lines)
+
+
+def _luminance(color) -> float:
+    r, g, b = mcolors.to_rgb(color)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def preflight(fig, spec: Optional[JournalSpec] = None) -> Report:
+    """Inspect a drawn figure for sub-spec fonts, lines, and gray ambiguity."""
+    spec = spec or _style.active()
+    if spec is None:
+        raise RuntimeError("No journal to check against; call pp.use('aps') or pass spec=.")
+
+    fig.canvas.draw()  # realize tick labels / autosized artists
+    fp = spec.font_pt
+    # Cap-height is an info-level nag aimed at text the *user* shrank below the
+    # journal's own defaults; don't fire it on the spec's chosen sizes (e.g. APS
+    # 7.5pt ticks are ~1.9mm cap-height by design — reporting them is just noise).
+    spec_floor_pt = min(fp.base, fp.tick, fp.legend, fp.panel)
+    findings: list[Finding] = []
+
+    for i, ax in enumerate(fig.axes):
+        texts = [("title", ax.title), ("x-label", ax.xaxis.label),
+                 ("y-label", ax.yaxis.label)]
+        texts += [("x-tick", t) for t in ax.get_xticklabels()]
+        texts += [("y-tick", t) for t in ax.get_yticklabels()]
+        leg = ax.get_legend()
+        if leg is not None:
+            texts += [("legend", t) for t in leg.get_texts()]
+
+        seen_kinds: set = set()
+        for kind, t in texts:
+            if not t.get_text():
+                continue
+            pt = t.get_fontsize()
+            loc = f"axes[{i}] {kind}"
+            if pt < fp.min_warn_pt:
+                findings.append(Finding(
+                    "warn", "min_font", loc, round(pt, 1), fp.min_warn_pt,
+                    f"{loc}: {pt:.1f}pt < {fp.min_warn_pt}pt minimum"))
+            elif (kind not in seen_kinds and pt < spec_floor_pt
+                  and fp.cap_height_mm(pt) < fp.min_cap_height_mm):
+                cap = fp.cap_height_mm(pt)
+                findings.append(Finding(
+                    "info", "min_font", loc, round(cap, 2), fp.min_cap_height_mm,
+                    f"{loc}: cap-height {cap:.2f}mm < {fp.min_cap_height_mm}mm "
+                    f"APS guideline (font {pt:.1f}pt)"))
+            seen_kinds.add(kind)
+
+        for j, line in enumerate(ax.get_lines()):
+            lw = line.get_linewidth()
+            if 0 < lw < spec.min_linewidth_pt:
+                findings.append(Finding(
+                    "warn", "min_linewidth", f"axes[{i}] Line2D #{j}",
+                    round(lw, 2), spec.min_linewidth_pt,
+                    f"axes[{i}] line #{j}: {lw:.2f}pt < "
+                    f"{spec.min_linewidth_pt}pt minimum weight"))
+
+        # collection-based artists (LineCollection from step/quiver/etc.) carry
+        # their own linewidths and would otherwise dodge the Line2D check.
+        for j, coll in enumerate(ax.collections):
+            try:
+                lws = [float(w) for w in coll.get_linewidths()]
+            except (TypeError, ValueError):
+                continue
+            thin = [w for w in lws if 0 < w < spec.min_linewidth_pt]
+            if thin:
+                w = min(thin)
+                findings.append(Finding(
+                    "warn", "min_linewidth", f"axes[{i}] collection #{j}",
+                    round(w, 2), spec.min_linewidth_pt,
+                    f"axes[{i}] collection #{j}: {w:.2f}pt < "
+                    f"{spec.min_linewidth_pt}pt minimum weight"))
+
+    # cycle-color grayscale separability (print is grayscale, APS H24)
+    try:
+        import matplotlib as mpl
+        from . import palettes
+        colors = mpl.rcParams["axes.prop_cycle"].by_key().get("color", [])
+        # Don't nag about the shipped default: Okabe-Ito is curated colorblind-safe,
+        # and its grayscale gaps are a known, accepted trade-off.
+        cur = [mcolors.to_hex(c).lower() for c in colors]
+        default = [mcolors.to_hex(c).lower() for c in palettes.OKABE_ITO]
+        is_default = bool(cur) and cur == default[:len(cur)]
+        lums = sorted(_luminance(c) for c in colors[:6])
+        gaps = [b - a for a, b in zip(lums, lums[1:])]
+        if not is_default and gaps and min(gaps) < 0.05:
+            findings.append(Finding(
+                "info", "gray_luminance", "color cycle", round(min(gaps), 3), 0.05,
+                "two cycle colors are near-identical in grayscale; check the "
+                "figure stays legible in print (APS H24)"))
+    except Exception:
+        pass
+
+    return Report(tuple(findings), spec_name=spec.name)

paperplot/mplstyle.py

@@ -0,0 +1,103 @@
+"""The zero-buy-in on-ramp: paperplot's look as a plain matplotlib style sheet.
+
+``figure()``/``save()`` are the product — they size to the real column width,
+embed fonts, and preflight. But the *look* (type scale, Okabe-Ito cycle, tick
+style, full box) is just rcParams, and rcParams travel as ``.mplstyle`` files.
+
+``export_mplstyle("aps")`` writes a style file; ``register_mplstyles()`` makes
+``plt.style.use("paperplot-aps")`` work in-process. Either way a user gets the
+styling with no API commitment, then graduates to ``pp.figure()`` for the part a
+style sheet *cannot* do — true sizing and preflight.
+
+We do NOT register on import: paperplot's first import stays silent and mutates
+no global matplotlib state. Registration is an explicit opt-in.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from cycler import Cycler
+
+from .registry import available, get_spec
+from .style import rcparams
+
+# Journal keys exposed as style sheets. Variants (prl/prx/prb) share APS styling,
+# so they'd produce identical sheets — we skip them here to keep the list clean.
+_STYLE_KEYS = ("aps", "nature", "ieee", "talk")
+
+
+def _format_value(key: str, value) -> str:
+    """Serialize one rcParam value to matplotlib ``.mplstyle`` syntax."""
+    if key == "axes.prop_cycle" and isinstance(value, Cycler):
+        # '#' starts a comment in .mplstyle files, so hex colors are written
+        # bare (no leading '#') — exactly how matplotlib's own matplotlibrc does.
+        colors = (c.lstrip("#") for c in value.by_key().get("color", []))
+        inner = ", ".join(f"'{c}'" for c in colors)
+        return f"cycler('color', [{inner}])"
+    if isinstance(value, bool):  # before int/float — bool is an int subclass
+        return "True" if value else "False"
+    if isinstance(value, (list, tuple)):
+        return ", ".join(str(v) for v in value)
+    return str(value)
+
+
+def to_mplstyle_text(journal, *, serif: bool = False, usetex: bool = False,
+                     palette=None, math: str = "cm",
+                     font_scale: float = 1.0) -> str:
+    """Render a journal's rcParams as ``.mplstyle`` file text.
+
+    Accepts the same styling options as :func:`paperplot.use`. The result is the
+    look only — it carries the journal's *default* (single-column) figure size,
+    not per-figure sizing, which is what ``pp.figure(width=...)`` is for.
+    """
+    spec = get_spec(journal) if not hasattr(journal, "revision") else journal
+    rc = rcparams(spec, serif=serif, usetex=usetex, palette=palette, math=math,
+                  font_scale=font_scale)
+    lines = [
+        f"# paperplot style for {spec.name} (revision {spec.revision}).",
+        "# Generated by paperplot.export_mplstyle — the look only.",
+        "# For journal-true sizing, font embedding, and preflight, use pp.figure()/pp.save().",
+        "",
+    ]
+    for key in sorted(rc):
+        lines.append(f"{key}: {_format_value(key, rc[key])}")
+    return "\n".join(lines) + "\n"
+
+
+def export_mplstyle(journal, path: Optional[str] = None, **opts) -> str:
+    """Write (and return) a ``.mplstyle`` file for ``journal``.
+
+    With no ``path``, returns the text without writing. Pass styling options
+    (``serif``, ``usetex``, ``palette``, ``math``, ``font_scale``) just like
+    :func:`paperplot.use`.
+    """
+    text = to_mplstyle_text(journal, **opts)
+    if path is not None:
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(text)
+    return text
+
+
+def register_mplstyles() -> list[str]:
+    """Register ``paperplot-<journal>`` styles into matplotlib's style library.
+
+    After calling this, ``plt.style.use("paperplot-aps")`` works (and the names
+    appear in ``plt.style.available``). Opt-in — paperplot never does this on
+    import. Returns the registered style names.
+    """
+    import matplotlib.style as mstyle
+
+    names = []
+    known = set(available())
+    for key in _STYLE_KEYS:
+        if key not in known:
+            continue
+        spec = get_spec(key)
+        name = f"paperplot-{key}"
+        # Library entries are applied via rcParams.update, so the live dict
+        # (cycler object intact) works directly — no text round-trip needed.
+        mstyle.library[name] = rcparams(spec)
+        names.append(name)
+    mstyle.available[:] = sorted(mstyle.library)
+    return names

paperplot/palettes.py

@@ -0,0 +1,190 @@
+"""Colors: a colorblind-safe qualitative cycle, sequential/diverging colormaps,
+and a small custom-palette registry. matplotlib-only (no seaborn).
+
+The core rule: qualitative cycles (for categories) and sequential/diverging
+colormaps (for ordered data) are *different things*. Using a sequential scheme
+as a categorical cycle is an enforced anti-pattern, not just a docstring note.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Dict, List, Sequence
+
+import matplotlib.colors as mcolors
+from matplotlib import colormaps
+
+# Okabe-Ito colorblind-safe qualitative palette (default cycle).
+OKABE_ITO: List[str] = [
+    "#0072B2",  # blue
+    "#D55E00",  # vermillion
+    "#009E73",  # green
+    "#CC79A7",  # reddish purple
+    "#E69F00",  # orange
+    "#56B4E9",  # sky blue
+    "#F0E442",  # yellow
+    "#000000",  # black
+]
+
+# Seaborn's qualitative palettes, hardcoded so they're available without seaborn.
+# The pairing that matters: MUTED for area/histogram *fills*, BRIGHT for *strokes*
+# (lines, reference markers). Muted fills under bright strokes keeps overlapping
+# filled shapes legible. See pp.fills() / pp.strokes().
+MUTED: List[str] = [
+    "#4878D0", "#EE854A", "#6ACC64", "#D65F5F", "#956CB4",
+    "#8C613C", "#DC7EC0", "#797979", "#D5BB67", "#82C6E2",
+]
+BRIGHT: List[str] = [
+    "#023EFF", "#FF7C00", "#1AC938", "#E8000B", "#8B2BE2",
+    "#9F4800", "#F14CC1", "#A3A3A3", "#FFC400", "#00D7FF",
+]
+DEEP: List[str] = [
+    "#4C72B0", "#DD8452", "#55A868", "#C44E52", "#8172B3",
+    "#937860", "#DA8BC3", "#8C8C8C", "#CCB974", "#64B5CD",
+]
+COLORBLIND: List[str] = [
+    "#0173B2", "#DE8F05", "#029E73", "#D55E00", "#CC78BC",
+    "#CA9161", "#FBAFE4", "#949494", "#ECE133", "#56B4E9",
+]
+PASTEL: List[str] = [
+    "#A1C9F4", "#FFB482", "#8DE5A1", "#FF9F9B", "#D0BBFF",
+    "#DEBB9B", "#FAB0E4", "#CFCFCF", "#FFFEA3", "#B9F2F0",
+]
+DARK: List[str] = [
+    "#001C7F", "#B1400D", "#12711C", "#8C0800", "#591E71",
+    "#592F0D", "#A23582", "#3C3C3C", "#B8850A", "#006374",
+]
+
+# Named categorical palettes resolvable by pp.palette("name").
+_BUILTIN: Dict[str, List[str]] = {
+    "muted": MUTED,
+    "bright": BRIGHT,
+    "deep": DEEP,
+    "colorblind": COLORBLIND,
+    "pastel": PASTEL,
+    "dark": DARK,
+}
+
+# Palettes designed to stay distinguishable under common color-vision deficiencies.
+# The seaborn "muted"/"bright"/etc. families are NOT in this set — they pair well
+# as fills/strokes but should not carry meaning across categorical *lines*.
+_CB_SAFE = {"okabe-ito", "colorblind"}
+
+# ColorBrewer + perceptual maps that are NOT valid categorical cycles.
+_SEQUENTIAL = {
+    "Blues", "BuGn", "BuPu", "GnBu", "Greens", "Greys", "OrRd", "Oranges",
+    "PuBu", "PuBuGn", "PuRd", "Purples", "RdPu", "Reds", "YlGn", "YlGnBu",
+    "YlOrBr", "YlOrRd", "viridis", "plasma", "inferno", "magma", "cividis",
+}
+_DIVERGING = {
+    "BrBG", "PiYG", "PRGn", "PuOr", "RdBu", "RdGy", "RdYlBu", "RdYlGn",
+    "Spectral", "coolwarm", "bwr", "seismic",
+}
+# True qualitative matplotlib colormaps — safe to use as categorical cycles.
+# (Continuous maps are stored as 256-entry ListedColormaps in modern matplotlib,
+# so a `hasattr(cmap, "colors")` test wrongly treats them as qualitative.)
+_QUALITATIVE = {
+    "Pastel1", "Pastel2", "Paired", "Accent", "Dark2",
+    "Set1", "Set2", "Set3", "tab10", "tab20", "tab20b", "tab20c",
+}
+_RESERVED = {"mpl", "okabe-ito", "okabe_ito"}
+
+_custom: Dict[str, List[str]] = {}
+
+
+def register_palette(name: str, colors: Sequence) -> None:
+    """Register a named categorical palette from a list of colors (hex or RGB)."""
+    key = name.strip().lower()
+    if key in _RESERVED:
+        raise ValueError(f"{name!r} is a reserved palette name.")
+    try:
+        hexed = [mcolors.to_hex(c) for c in colors]
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"Invalid color in palette {name!r}: {e}") from None
+    if not hexed:
+        raise ValueError("A palette needs at least one color.")
+    _custom[key] = hexed
+
+
+def cmap(name: str):
+    """Return a matplotlib Colormap for ordered/heatmap data."""
+    return colormaps[name]  # modern API; cm.get_cmap was removed in mpl 3.9
+
+
+def palette(name: str = "okabe-ito", n: int | None = None) -> List[str]:
+    """Return a list of categorical colors.
+
+    Registered names and qualitative schemes are returned directly; sequential or
+    diverging scheme names raise a warning (that's the anti-pattern) and are
+    sampled as a fallback.
+    """
+    key = name.strip().lower()
+    if key in _custom:
+        cols = list(_custom[key])
+    elif key in ("okabe-ito", "okabe_ito"):
+        cols = list(OKABE_ITO)
+    elif key == "mpl":
+        cols = list(mcolors.TABLEAU_COLORS.values())
+    elif key in _BUILTIN:
+        cols = list(_BUILTIN[key])
+    elif name in _QUALITATIVE:
+        # A true qualitative colormap (Set2, Dark2, tab10…): take its discrete swatches.
+        c = colormaps[name]
+        k = n or getattr(c, "N", 8)
+        cols = [mcolors.to_hex(c(i % c.N)) for i in range(k)]
+    else:
+        # Any continuous map used as a categorical cycle is the anti-pattern —
+        # whether it's a known sequential/diverging name or an unlisted one
+        # (turbo, jet, hsv…). Warn and sample a *small* even set, never dump c.N.
+        try:
+            c = colormaps[name]
+        except KeyError:
+            raise ValueError(
+                f"Unknown palette or colormap {name!r}. "
+                f"Categorical palettes: {available_palettes()}; "
+                f"for ordered data use pp.cmap({name!r})."
+            ) from None
+        warnings.warn(
+            f"{name!r} is a continuous colormap; using it as a categorical "
+            f"cycle is an anti-pattern (adjacent categories look ordered/"
+            f"low-contrast). Use pp.cmap({name!r}) for ordered data, or a "
+            f"qualitative palette for categories.",
+            stacklevel=2,
+        )
+        k = n or 6
+        cols = [mcolors.to_hex(c(i / max(k - 1, 1))) for i in range(k)]
+
+    if n is not None:
+        cols = [cols[i % len(cols)] for i in range(n)]
+    return cols
+
+
+def fills(n: int | None = None) -> List[str]:
+    """Muted palette for area / histogram **fills** (pairs with ``strokes()``)."""
+    return palette("muted", n)
+
+
+def strokes(n: int | None = None) -> List[str]:
+    """Bright palette for **strokes** — lines, outlines, reference markers."""
+    return palette("bright", n)
+
+
+def is_colorblind_safe(name: str) -> bool:
+    """Whether a named palette stays distinguishable under color-vision deficiency."""
+    return name.strip().lower().replace("_", "-") in _CB_SAFE
+
+
+def available_palettes() -> List[str]:
+    """Names of all resolvable categorical palettes (built-in + registered)."""
+    names = ["okabe-ito", *_BUILTIN, "mpl"]
+    names += [k for k in _custom if k not in names]
+    return names
+
+
+def resolve_cycle(value) -> List[str]:
+    """Coerce a palette name / color list / None into a list of cycle colors."""
+    if value is None:
+        return list(OKABE_ITO)
+    if isinstance(value, str):
+        return palette(value)
+    return [mcolors.to_hex(c) for c in value]