paperplot-quantum 0.1.0__py3-none-any.whl

paperplot/__init__.py

@@ -0,0 +1,77 @@
+"""paperplot — publication-correct matplotlib figures, journal by journal.
+
+Quickstart::
+
+    import paperplot as pp
+
+    pp.use("aps")                       # set the journal once
+    fig, ax = pp.figure(width="single") # journal-sized, journal-styled
+    ax.plot(x, y)
+    pp.save(fig, "fig1.pdf")            # embeds fonts, runs preflight()
+
+Ships Physical Review (APS, incl. PRL/PRX/PRB), Nature, and IEEE, plus a "talk"
+presentation target. matplotlib-only core; seaborn/IPython optional.
+"""
+
+from __future__ import annotations
+
+from .journals import FontScale, JournalSpec
+from .layout import Width, Row, Grid
+from .lint import Finding, Report, preflight
+from .palettes import (
+    OKABE_ITO,
+    available_palettes,
+    cmap,
+    fills,
+    is_colorblind_safe,
+    palette,
+    register_palette,
+    strokes,
+)
+from .preview import grayscale_proof, preview_in_page, show
+from .registry import available, get_spec
+from .style import active, apply, rcparams, reset, style, use
+from .core import (
+    clean_shared_axes,
+    despine,
+    figure,
+    panel_labels,
+    subplots,
+    composite,
+)
+from .plots import (
+    data_fit_band,
+    hist_filled,
+    hist_outline,
+    show_palettes,
+    swatches,
+)
+from .save import save
+from .mplstyle import export_mplstyle, register_mplstyles, to_mplstyle_text
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # types
+    "JournalSpec", "FontScale", "Width", "Report", "Finding",
+    "Row", "Grid",
+    # journal / style
+    "use", "style", "reset", "active", "apply", "rcparams",
+    "get_spec", "available",
+    # figures
+    "figure", "subplots", "composite", "save",
+    # helpers
+    "panel_labels", "despine", "clean_shared_axes",
+    # colors
+    "palette", "cmap", "register_palette", "OKABE_ITO", "fills", "strokes",
+    "available_palettes", "is_colorblind_safe",
+    # plot helpers
+    "hist_outline", "hist_filled", "data_fit_band", "swatches", "show_palettes",
+    # preview
+    "show", "preview_in_page", "grayscale_proof",
+    # mplstyle on-ramp
+    "export_mplstyle", "to_mplstyle_text", "register_mplstyles",
+    # lint
+    "preflight",
+    "__version__",
+]

paperplot/core.py

@@ -0,0 +1,228 @@
+"""The figure maker and axes helpers.
+
+``figure()`` (aliased ``subplots``) is the one function users touch first; it
+sizes to the journal column and applies the spec's style. ``panel_labels`` /
+``despine`` / ``clean_shared_axes`` are the small layout helpers.
+"""
+
+from __future__ import annotations
+
+import string
+from typing import Optional, Sequence
+
+import importlib
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+# The public pp.style() function shadows the style submodule on the package, so
+# reach the module via sys.modules rather than attribute lookup.
+_style = importlib.import_module("paperplot.style")
+
+
+def figure(width="single", *, aspect="golden", height=None, nrows=1, ncols=1,
+           journal=None, palette=None, serif=None, math=None, font_scale=None,
+           sharex=False, sharey=False,
+           height_ratios: Optional[Sequence[float]] = None,
+           width_ratios: Optional[Sequence[float]] = None,
+           constrained: bool = True, **subplot_kw):
+    """Create a journal-sized, journal-styled figure + axes.
+
+    Returns ``(fig, ax)`` for a 1x1 grid, else ``(fig, ndarray[Axes])`` — same
+    shape contract as ``plt.subplots``. ``serif``/``palette``/``math``/
+    ``font_scale`` left as ``None`` inherit whatever ``pp.use()`` set.
+    """
+    spec = _style.resolve_spec(journal)
+    _style.apply(spec, serif=serif, palette=palette, math=math,
+                 font_scale=font_scale)
+
+    figsize = spec.figsize(width, aspect=aspect, height=height)
+
+    gridspec_kw = {}
+    if height_ratios is not None:
+        gridspec_kw["height_ratios"] = list(height_ratios)
+    if width_ratios is not None:
+        gridspec_kw["width_ratios"] = list(width_ratios)
+
+    fig, axes = plt.subplots(
+        nrows, ncols, figsize=figsize, sharex=sharex, sharey=sharey,
+        layout="constrained" if constrained else None,
+        gridspec_kw=gridspec_kw or None, **subplot_kw,
+    )
+    return fig, axes
+
+
+subplots = figure  # alias
+
+
+def _flatten(axes):
+    if isinstance(axes, np.ndarray):
+        return list(axes.ravel())
+    if isinstance(axes, (list, tuple)):
+        return list(axes)
+    return [axes]
+
+
+def _default_labels(n):
+    """a, b, …, z, aa, ab, … — enough letters for ``n`` panels (>26 safe)."""
+    import itertools
+    out = []
+    width = 1
+    while len(out) < n:
+        for combo in itertools.product(string.ascii_lowercase, repeat=width):
+            out.append("".join(combo))
+            if len(out) >= n:
+                break
+        width += 1
+    return out
+
+
+def panel_labels(axes, labels=None, *, loc="outside", offset_pt=None,
+                 nudge="first-col", size=None, weight="bold", fmt="{}",
+                 color="black", bbox=False, reserve=None):
+    """Stamp ``a, b, c…`` panel letters on each axes.
+
+    Args:
+        loc: ``"outside"`` (above the top-left corner — the journal default) or
+            ``"inside"`` (just inside the top-left of the data area).
+        offset_pt: ``(dx, dy)`` nudge in points. Defaults to ``(-8, 2)`` outside
+            (letters sit over the left margin) / ``(3, -3)`` inside.
+        nudge: outside only — which columns shift left by ``dx``.
+            ``"first-col"`` (default) shifts only the outer-left column into the
+            margin, so inner columns don't widen the inter-column gap;
+            ``"all"`` shifts every label; ``"none"`` ignores ``dx``.
+        size: font size; defaults to the active journal's panel size.
+        bbox: draw a white background box behind each letter (good for
+            ``loc="inside"`` over data).
+        reserve: whether labels reserve layout space. Default ``True`` for
+            ``"outside"`` (so the top row never clips) and ``False`` for
+            ``"inside"`` (never clips anyway — no reflow).
+
+    ``annotation_clip`` is always off, so the axes never hide a label.
+    """
+    axs = _flatten(axes)
+    if labels is None:
+        labels = _default_labels(len(axs))   # never runs out past 26 panels
+    if size is None:
+        spec = _style.active()
+        size = spec.font_pt.panel if spec is not None else 9.0
+
+    inside = loc == "inside"
+    if offset_pt is None:
+        offset_pt = (3, -3) if inside else (-8, 2)
+    dx, dy = offset_pt
+    va = "top" if inside else "bottom"
+    if reserve is None:
+        reserve = not inside
+    box = (dict(boxstyle="square,pad=0.15", fc="white", ec="none", alpha=0.85)
+           if bbox else None)
+
+    out = []
+    for ax, lab in zip(axs, labels):
+        ddx = dx
+        if not inside and nudge != "all":
+            # left-shift only escapes into the OUTER margin; inner columns sit
+            # above their corner so they never widen the inter-column gap.
+            ss = ax.get_subplotspec()
+            if nudge == "none" or (ss is not None and ss.colspan.start != 0):
+                ddx = 0
+        ann = ax.annotate(
+            fmt.format(lab), xy=(0, 1), xycoords="axes fraction",
+            xytext=(ddx, dy), textcoords="offset points",
+            ha="left", va=va, fontsize=size, fontweight=weight, color=color,
+            annotation_clip=False, bbox=box)
+        ann.set_in_layout(reserve)
+        out.append(ann)
+    return out
+
+
+def despine(axes, *, top=True, right=True, left=False, bottom=False):
+    """Hide the named spines (and their ticks). Inverse of the full-box default."""
+    sides = {"top": top, "right": right, "left": left, "bottom": bottom}
+    for ax in _flatten(axes):
+        for side, drop in sides.items():
+            if drop:
+                ax.spines[side].set_visible(False)
+        ax.tick_params(top=not top, right=not right,
+                       left=not left, bottom=not bottom,
+                       labeltop=False, labelright=False)
+
+
+def clean_shared_axes(fig):
+    """On a shared grid, keep tick labels/axis labels only on the outer edge."""
+    for ax in fig.axes:
+        ss = ax.get_subplotspec()
+        if ss is None:
+            continue
+        if not ss.is_last_row():
+            ax.set_xlabel("")
+            ax.tick_params(labelbottom=False)
+        if not ss.is_first_col():
+            ax.set_ylabel("")
+            ax.tick_params(labelleft=False)
+
+
+def _build_grid(fig, grid_spec):
+    """Builds the exact absolute coordinates for the grid."""
+    # 1. Compute total figure dimensions in inches
+    total_width = (grid_spec.margins["left"] + 
+                   grid_spec.ncols * grid_spec.col_width + 
+                   (grid_spec.ncols - 1) * grid_spec.wspace + 
+                   grid_spec.margins["right"])
+    
+    total_height = grid_spec.margins["top"] + grid_spec.margins["bottom"]
+    for r in grid_spec.rows:
+        total_height += r.height + r.gap_above
+        
+    # Resize figure to the exact required size
+    fig.set_size_inches(total_width, total_height)
+    
+    axes_array = np.empty((len(grid_spec.rows), grid_spec.ncols), dtype=object)
+    row_names = [r.name for r in grid_spec.rows]
+    
+    # 2. Compute column horizontal positions (relative 0.0 to 1.0)
+    lefts = []
+    for c in range(grid_spec.ncols):
+        x = grid_spec.margins["left"] + c * (grid_spec.col_width + grid_spec.wspace)
+        lefts.append(x / total_width)
+    w_frac = grid_spec.col_width / total_width
+    
+    # 3. Compute row vertical positions from top to bottom
+    current_y = total_height - grid_spec.margins["top"]
+    
+    for r_idx, r in enumerate(grid_spec.rows):
+        current_y -= r.gap_above
+        current_y -= r.height
+        
+        y_frac = current_y / total_height
+        h_frac = r.height / total_height
+        
+        for c_idx in range(grid_spec.ncols):
+            # Create exact axis position
+            ax = fig.add_axes([lefts[c_idx], y_frac, w_frac, h_frac])
+            axes_array[r_idx, c_idx] = ax
+            
+            # Handle attachment semantics
+            if r.attached and r_idx > 0:
+                ax_above = axes_array[r_idx - 1, c_idx]
+                ax.sharex(ax_above)
+                ax_above.tick_params(labelbottom=False)
+                ax_above.set_xlabel("")
+                
+    from .layout import GridAxesDict
+    return GridAxesDict(axes_array, row_names)
+
+
+def composite(grid=None, journal=None, palette=None, serif=None, math=None, font_scale=None):
+    """Create a composite figure using the precise Grid absolute layout engine.
+    
+    Returns ``(fig, ax_dict)`` where ax_dict acts as both a 2D ndarray and a dictionary
+    addressable by ``ax["row_name", col_index]``.
+    """
+    spec = _style.resolve_spec(journal)
+    _style.apply(spec, serif=serif, palette=palette, math=math, font_scale=font_scale)
+    
+    # Create an empty figure with NO layout engine to prevent automatic squishing
+    fig = plt.figure(figsize=(1, 1), layout="none")
+    ax_dict = _build_grid(fig, grid)
+    return fig, ax_dict

paperplot/data/fonts/GUST-FONT-LICENSE.txt

@@ -0,0 +1,29 @@
+% This is version 1.0, dated 22 June 2009, of the GUST Font License.
+% (GUST is the Polish TeX Users Group, https://www.gust.org.pl)
+%
+% For the most recent version of this license see
+% https://www.gust.org.pl/fonts/licenses/GUST-FONT-LICENSE.txt
+% or
+% https://tug.org/fonts/licenses/GUST-FONT-LICENSE.txt
+%
+% This work may be distributed and/or modified under the conditions
+% of the LaTeX Project Public License, either version 1.3c of this
+% license or (at your option) any later version.
+% 
+% Please also observe the following clause:
+% 1) it is requested, but not legally required, that derived works be
+%    distributed only after changing the names of the fonts comprising this
+%    work and given in an accompanying "manifest", and that the
+%    files comprising the Work, as listed in the manifest, also be given
+%    new names. Any exceptions to this request are also given in the
+%    manifest.
+%    
+%    We recommend the manifest be given in a separate file named
+%    MANIFEST-<fontid>.txt, where <fontid> is some unique identification
+%    of the font family. If a separate "readme" file accompanies the Work, 
+%    we recommend a name of the form README-<fontid>.txt.
+%
+% The latest version of the LaTeX Project Public License is in
+% https://www.latex-project.org/lppl.txt and version 1.3c or later
+% is part of all distributions of LaTeX version 2006/05/20 or later.
+

paperplot/data/fonts/LICENSE.md

@@ -0,0 +1,22 @@
+# Bundled fonts
+
+## TeX Gyre Heros (`texgyreheros-*.otf`, version 2.004)
+
+A free, metric-compatible substitute for **Helvetica**, bundled so paperplot
+figures render in a Helvetica/Arial-like face on *any* machine — Arial and
+Helvetica themselves are proprietary and cannot be redistributed.
+
+- Family name in matplotlib: **`TeX Gyre Heros`**
+- Version bundled: **2.004** (original, unmodified upstream OpenType releases)
+- Source: GUST e-foundry — https://www.gust.org.pl/projects/e-foundry/tex-gyre/heros
+- License: **GUST Font License (GFL)** — a free, LPPL-based license that permits
+  redistribution and bundling. Full verbatim text ships alongside these fonts in
+  [`GUST-FONT-LICENSE.txt`](GUST-FONT-LICENSE.txt)
+  (also: http://tug.org/fonts/licenses/GUST-FONT-LICENSE.txt).
+
+Copyright (verbatim from the embedded font metadata):
+
+> Copyright 2006, 2009 for TeX Gyre extensions by B. Jackowski and J.M. Nowacki
+> (on behalf of TeX users groups).
+
+The fonts are provided "as is" without warranty of any kind.

paperplot/data/journals.toml

@@ -0,0 +1,123 @@
+# paperplot journal specifications (data, not code).
+# Edit the numbers here to update specs; bump `revision` when content changes.
+schema_version = 1
+
+# --- Physical Review (APS): PRL / PRX / PRB / PRA / PRApplied / PRResearch ---
+[journal.aps]
+name = "Physical Review"
+revision = "2024-01"
+page_height_mm = 235.0       # usable two-column text height on US-letter (REVTeX)
+caption_reserve_mm = 25.0    # vertical space kept free for the caption on full-page floats
+min_linewidth_pt = 0.5       # APS minimum line weight (0.18 mm)
+page_body_pt = 10.0          # REVTeX manuscript body text size (for preview_in_page)
+font_family = ["Arial", "Helvetica", "TeX Gyre Heros", "DejaVu Sans"]
+
+[journal.aps.widths_mm]
+single = 86.0                # 8.6 cm, 3 3/8 in
+onehalf = 120.0             # advisory, not a fixed APS spec
+double = 178.0              # 17.8 cm, 7 in
+
+[journal.aps.font_pt]
+base = 8.0
+tick = 7.5
+panel = 9.0
+legend = 7.5
+
+[journal.aps.rasterize_dpi]
+line = 600
+photo = 300
+
+# Variants share APS geometry; they override only what differs.
+[journal.aps.variants.prl]
+revision = "2024-01+prl"
+
+[journal.aps.variants.prx]
+revision = "2024-01+prx"
+
+[journal.aps.variants.prb]
+revision = "2024-01+prb"
+
+# --- Nature family ------------------------------------------------------------
+[journal.nature]
+name = "Nature"
+revision = "2024-01"
+page_height_mm = 170.0       # max figure height (leaves room for the legend)
+caption_reserve_mm = 0.0     # the 170 mm cap already excludes legend space
+min_linewidth_pt = 0.5
+page_body_pt = 9.0           # Nature manuscript body text size (for preview_in_page)
+font_family = ["Arial", "Helvetica", "TeX Gyre Heros", "DejaVu Sans"]
+
+[journal.nature.widths_mm]
+single = 89.0
+onehalf = 120.0
+double = 183.0
+
+[journal.nature.font_pt]
+base = 7.0                   # Nature: max 7 pt for figure body text
+tick = 6.5
+panel = 8.0                  # panel letters: 8 pt bold
+legend = 6.5
+min_warn_pt = 5.0           # Nature minimum text size
+min_cap_height_mm = 1.3
+
+[journal.nature.rasterize_dpi]
+line = 600
+photo = 300
+
+# --- IEEE (Transactions / conference two-column) ------------------------------
+[journal.ieee]
+name = "IEEE"
+revision = "2024-01"
+page_height_mm = 235.0       # usable column text height (US-letter, IEEEtran)
+caption_reserve_mm = 0.0
+min_linewidth_pt = 0.5
+page_body_pt = 10.0          # IEEEtran body text size (for preview_in_page)
+# IEEE figures are commonly Times; pass serif=True. This is the sans fallback.
+font_family = ["Arial", "Helvetica", "TeX Gyre Heros", "DejaVu Sans"]
+
+[journal.ieee.widths_mm]
+single = 88.9                # 3.5 in column
+onehalf = 120.0
+double = 181.9               # 7.16 in text width (2 x 3.5 in cols + 0.16 in gutter)
+
+[journal.ieee.font_pt]
+base = 8.0
+tick = 7.0
+panel = 9.0
+legend = 7.0
+min_warn_pt = 6.0
+min_cap_height_mm = 1.5
+
+[journal.ieee.rasterize_dpi]
+line = 600
+photo = 300
+
+# --- Presentation target (slides / talks) -------------------------------------
+# Not a journal: a sizing/typography target for projected figures. Larger type,
+# thicker lines (derived from min_linewidth_pt), wider default. preflight's
+# cap-height rule is irrelevant here, so the floor is set permissively.
+[journal.talk]
+name = "Presentation"
+revision = "2024-01"
+page_height_mm = 190.0       # ~16:9 slide content area
+caption_reserve_mm = 0.0
+min_linewidth_pt = 1.0       # thicker strokes survive projection
+page_body_pt = 18.0
+font_family = ["Arial", "Helvetica", "TeX Gyre Heros", "DejaVu Sans"]
+
+[journal.talk.widths_mm]
+single = 130.0               # half-slide figure
+onehalf = 180.0
+double = 240.0               # ~full-slide figure
+
+[journal.talk.font_pt]
+base = 18.0
+tick = 16.0
+panel = 20.0
+legend = 16.0
+min_warn_pt = 12.0
+min_cap_height_mm = 0.0
+
+[journal.talk.rasterize_dpi]
+line = 600
+photo = 200

paperplot/fonts.py

@@ -0,0 +1,45 @@
+"""Font registration.
+
+Only redistributably-licensed faces would ever be *bundled* (DejaVu/Liberation/
+TeX-Gyre Heros); Arial/Helvetica are runtime *preferences*, never shipped here.
+If a ``data/fonts`` directory exists, its fonts are registered; otherwise this is
+a silent no-op and matplotlib's resolution + the spec's fallback chain apply.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+from matplotlib import font_manager
+
+_done = False
+
+
+def register_bundled(verbose: bool = False) -> int:
+    """Register any bundled fonts. Idempotent. Returns the count added."""
+    global _done
+    if _done:
+        return 0
+    _done = True
+    try:
+        font_dir = files("paperplot").joinpath("data", "fonts")
+        if not font_dir.is_dir():
+            return 0
+        added = 0
+        for path in font_manager.findSystemFonts(fontpaths=[str(font_dir)]):
+            font_manager.fontManager.addfont(path)
+            if verbose:
+                print(f"registered {path}")
+            added += 1
+        return added
+    except (FileNotFoundError, OSError):
+        return 0
+
+
+def available_family(preferences) -> str | None:
+    """Return the first font family from ``preferences`` actually installed."""
+    installed = {f.name for f in font_manager.fontManager.ttflist}
+    for fam in preferences:
+        if fam in installed:
+            return fam
+    return None

paperplot/journals.py

@@ -0,0 +1,57 @@
+"""The journal spec data types: ``FontScale`` and ``JournalSpec``.
+
+These are pure, frozen data. The only behavior is ``figsize`` (pure geometry,
+delegated to :mod:`paperplot.layout`). Styling (``rcparams``) and validation
+(``preflight``) live in their own modules as free functions so this stays plain,
+testable data with no matplotlib-Figure coupling.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Tuple
+
+
+@dataclass(frozen=True)
+class FontScale:
+    """Point sizes plus the APS cap-height floor."""
+
+    base: float = 8.0       # axis labels, title, default text
+    tick: float = 7.5       # tick labels
+    panel: float = 9.0      # (a)(b)(c) panel letters, bold
+    legend: float = 7.5
+    min_warn_pt: float = 7.0          # preflight warns below this (defaults pass)
+    min_cap_height_mm: float = 2.0    # APS rule (reported at info level)
+    cap_height_ratio: float = 0.72    # cap-height / em for sans faces
+
+    def cap_height_mm(self, pt: float) -> float:
+        """Approximate printed cap-height of ``pt`` text, in mm."""
+        return pt * (25.4 / 72.0) * self.cap_height_ratio
+
+
+@dataclass(frozen=True)
+class JournalSpec:
+    """Immutable, queryable description of one journal's figure rules."""
+
+    name: str
+    revision: str
+    widths_mm: Mapping[str, float]
+    page_height_mm: float
+    caption_reserve_mm: float
+    font_family: Tuple[str, ...]
+    font_pt: FontScale = field(default_factory=FontScale)
+    min_linewidth_pt: float = 0.5
+    page_body_pt: float = 10.0  # manuscript body text size (for preview_in_page)
+    rasterize_dpi: Mapping[str, int] = field(
+        default_factory=lambda: {"line": 600, "photo": 300}
+    )
+
+    def width_in(self, width="single") -> float:
+        from . import layout
+
+        return layout.width_in(self, width)
+
+    def figsize(self, width="single", aspect="golden", height=None):
+        from . import layout
+
+        return layout.figsize(self, width, aspect=aspect, height=height)