plotastro 1.0.0__py3-none-any.whl

plotastro/__init__.py

@@ -0,0 +1,68 @@
+"""plotastro — publication-quality matplotlib figures for astronomy journals.
+
+One import gives you journal-matched styles, correctly sized figures and a
+colour-blind-friendly palette:
+
+    import matplotlib.pyplot as plt
+    import plotastro as pa
+
+    pa.set_style("mnras")          # or "aanda", "apj", "oja", "prd", ...
+    fig, ax = pa.subplots()        # one-column, golden-ratio figure
+    ax.plot(x, y, label="model")
+    ax.set_xlabel("$x$")
+    ax.legend()
+    pa.savefig("myplot")           # -> myplot.pdf
+
+Importing plotastro also registers the styles with matplotlib itself, so
+``plt.style.use("mnras")`` works anywhere afterwards.
+
+Supported journals: MNRAS, RASTI, A&A, ApJ/ApJL (AASTeX), the Open Journal
+of Astrophysics, PRD/PRL (REVTeX), JCAP and Nature Astronomy — plus
+"thesis" and "beamer" width presets. See the README for the full tutorial.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+import matplotlib as _mpl
+import matplotlib.style as _mstyle
+
+from ._authors import authorlist
+from ._core import (
+    GOLDEN, JOURNALS, STYLE_DIR,
+    current_journal, figsize, savefig, set_size, set_style, subplots, use,
+)
+from ._colors import (
+    COLORS, CYCLE, OKABE_ITO, PAIRED, PETROFF10,
+    check_colors, check_figure, darken, lighten, simulate_cvd,
+)
+from ._extras import (
+    LINESTYLES, MARKERS,
+    label_panels, show_colors, show_linestyles, show_markers, style_cycler,
+)
+
+try:
+    __version__ = _version("plotastro")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0+unknown"
+
+__all__ = [
+    "set_style", "use", "figsize", "subplots", "savefig", "current_journal",
+    "authorlist",
+    "JOURNALS", "GOLDEN", "STYLE_DIR",
+    "COLORS", "CYCLE", "OKABE_ITO", "PETROFF10", "PAIRED",
+    "lighten", "darken", "simulate_cvd", "check_colors", "check_figure",
+    "MARKERS", "LINESTYLES", "style_cycler", "label_panels",
+    "show_colors", "show_markers", "show_linestyles",
+    "set_size",
+]
+
+
+def _register_styles():
+    """Make the bundled styles available as plt.style.use("mnras") etc."""
+    for path in STYLE_DIR.glob("*.mplstyle"):
+        _mstyle.library[path.stem] = _mpl.rc_params_from_file(
+            path, use_default_template=False)
+    _mstyle.available[:] = sorted(_mstyle.library)
+
+
+_register_styles()

plotastro/_authors.py

@@ -0,0 +1,302 @@
+"""Generate journal-ready LaTeX author/affiliation blocks from a CSV file.
+
+Works directly with real collaboration author lists. Recognised columns
+(header names are case-insensitive; **any other column is ignored**, so
+collaboration bookkeeping like ``JoinedAsBuilder`` is fine):
+
+    Authorname     display name, e.g. "Behnood Bandi" (alias: "name");
+                   if absent, built from "Firstname" + "Lastname"
+    Affiliation    one or more affiliations separated by ";"
+                   (aliases: "affiliations", "affil", "affiliation1", ...)
+    ORCID          optional
+    Email          optional; authors with an email are marked corresponding
+
+Example (a typical collaboration list — see examples/authors_example.csv
+for the full file)::
+
+    Lastname,Firstname,Authorname,Email,JoinedAsBuilder,Affiliation,ORCID,
+    Bandi,Behnood,Behnood Bandi, b.bandi@sussex.ac.uk, False,"Astronomy Centre, University of Sussex, Falmer, Brighton BN1 9QH, UK",0000-0001-5838-3903,
+    Rocher,Antoine,Antoine Rocher,antoine.rocher@epfl.ch,False,"EPFL, \\'{E}cole polytechnique f\\'{e}d\\'{e}rale de Lausanne, Chemin des Maillettes, 51, 1290 Versoix, Switzerland",0000-0003-4349-6424,
+
+Notes:
+
+- LaTeX already present in the CSV (accents like ``\\'{e}``, maths, ...)
+  is passed through untouched; only unescaped ``& % # _`` are escaped.
+- Whitespace around values is stripped (`` b.bandi@...`` is fine).
+- An author appearing on **several rows** (one per affiliation, as some
+  collaborations do) is merged into one entry with all affiliations.
+- Author order = row order; affiliations are numbered in order of first
+  appearance and shared between authors automatically.
+
+Usage from Python::
+
+    import plotastro as pa
+    print(pa.authorlist("authors.csv", journal="mnras"))
+
+or from the command line (installed with the package)::
+
+    plotastro-authors authors.csv --journal mnras
+    plotastro-authors authors.csv -j apj -o authors.tex
+
+The output is a starting point that compiles with the journal's template —
+fine-tune addresses, footnotes etc. in the .tex file.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import re
+import string
+from pathlib import Path
+
+# Journals sharing an author-block format:
+_FORMATS = {
+    "mnras": "mnras", "rasti": "mnras",
+    "aanda": "aanda",
+    "apj": "aastex", "oja": "aastex",
+    "prd": "revtex",
+    "jcap": "jcap",
+    "generic": "generic", "natastro": "generic",
+    "thesis": "generic", "beamer": "generic",
+}
+
+def _escape(text):
+    """Escape unescaped & % # _ for LaTeX; leave existing LaTeX alone."""
+    return re.sub(r"(?<!\\)([&%#_])", r"\\\1", str(text).strip())
+
+
+def _norm_key(key):
+    return str(key).strip().lower().replace(" ", "").replace("_", "")
+
+
+def _read_authors(source):
+    """Return a list of {name, affils, orcid, email} dicts.
+
+    `source` is a CSV path, or an already-parsed list of dicts (with the
+    same keys as the CSV columns) for programmatic use. See the module
+    docstring for the recognised columns; rows repeating an author's name
+    are merged (extra affiliations appended).
+    """
+    if isinstance(source, (str, Path)):
+        with open(source, newline="", encoding="utf-8-sig") as f:
+            rows = list(csv.DictReader(f))
+    else:
+        rows = [dict(row) for row in source]
+
+    authors, seen = [], {}
+    for raw in rows:
+        row = {_norm_key(k): (v or "").strip() for k, v in raw.items() if k}
+        name = (row.get("authorname") or row.get("name") or " ".join(
+            part for part in (row.get("firstname"), row.get("lastname")) if part))
+        if not name:
+            continue
+        affils = []
+        for key in sorted(row):  # affiliation, affiliations, affiliation1, ...
+            if key.startswith("affil"):
+                affils += [a.strip() for a in row[key].split(";") if a.strip()]
+
+        author = seen.get(name.lower())
+        if author is None:
+            author = {"name": _escape(name), "affils": [],
+                      "orcid": "", "email": ""}
+            seen[name.lower()] = author
+            authors.append(author)
+        for aff in affils:
+            escaped = _escape(aff)
+            if escaped not in author["affils"]:
+                author["affils"].append(escaped)
+        author["orcid"] = author["orcid"] or row.get("orcid", "")
+        author["email"] = author["email"] or row.get("email", "")
+    if not authors:
+        raise ValueError(
+            "No authors found — the CSV needs an 'Authorname' or 'name' "
+            "column (or 'Firstname'/'Lastname') with at least one "
+            "non-empty row.")
+    return authors
+
+
+def _affiliation_index(authors):
+    """Ordered unique affiliations -> 1-based numbering."""
+    index = {}
+    for a in authors:
+        for aff in a["affils"]:
+            index.setdefault(aff, len(index) + 1)
+    return index
+
+
+def _short_authors(authors):
+    """Running-head form: 'B. Bandi et al.', 'Doe & Roe', or 'B. Bandi'."""
+    def surname(a):
+        return a["name"].split()[-1]
+
+    first = authors[0]["name"].split()
+    initial = f"{first[0][0]}. {first[-1]}" if len(first) > 1 else first[0]
+    if len(authors) == 1:
+        return initial
+    if len(authors) == 2:
+        return f"{surname(authors[0])} \\& {surname(authors[1])}"
+    return f"{initial} et al."
+
+
+def _sup(author, index):
+    nums = ",".join(str(n) for n in sorted(index[a] for a in author["affils"]))
+    return f"$^{{{nums}}}$" if nums else ""
+
+
+def _corresponding(authors):
+    """First author with an email — the only one footnoted in the
+    single-\\thanks formats (MNRAS, A&A)."""
+    return next((a for a in authors if a["email"]), None)
+
+
+def _fmt_mnras(authors, index):
+    corr = _corresponding(authors)
+    lines = [f"\\author[{_short_authors(authors)}]{{"]
+    for i, a in enumerate(authors):
+        thanks = f"\\thanks{{E-mail: {a['email']}}}" if a is corr else ""
+        if len(authors) > 1 and i == len(authors) - 1:
+            lines.append(f"and {a['name']}{_sup(a, index)}{thanks}")
+        elif i >= len(authors) - 2:  # no comma before the final 'and'
+            lines.append(f"{a['name']}{_sup(a, index)}{thanks}")
+        else:
+            lines.append(f"{a['name']},{_sup(a, index)}{thanks}")
+    lines += ["\\\\", "% List of institutions"]
+    insts = [f"$^{{{n}}}$" + aff for aff, n in index.items()]
+    lines.append("\\\\\n".join(insts))
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def _fmt_aanda(authors, index):
+    corr = _corresponding(authors)
+    parts = []
+    for a in authors:
+        nums = ",".join(str(n) for n in sorted(index[x] for x in a["affils"]))
+        inst = f"\\inst{{{nums}}}" if nums else ""
+        thanks = f"\\thanks{{\\email{{{a['email']}}}}}" if a is corr else ""
+        parts.append(f"{a['name']}{inst}{thanks}")
+    author_block = "\\author{" + "\n        \\and ".join(parts) + "}"
+    inst_block = ("\\institute{" +
+                  "\n           \\and ".join(index) + "}")
+    return author_block + "\n\n" + inst_block
+
+
+def _fmt_aastex(authors, index):
+    blocks = []
+    corresponding = _corresponding(authors)
+    if corresponding:
+        blocks.append(f"\\correspondingauthor{{{corresponding['name']}}}\n"
+                      f"\\email{{{corresponding['email']}}}")
+    for a in authors:
+        opt = f"[{a['orcid']}]" if a["orcid"] else ""
+        lines = [f"\\author{opt}{{{a['name']}}}"]
+        lines += [f"\\affiliation{{{aff}}}" for aff in a["affils"]]
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def _fmt_revtex(authors, index):
+    blocks = []
+    for a in authors:
+        lines = [f"\\author{{{a['name']}}}"]
+        if a["email"]:
+            lines.append(f"\\email{{{a['email']}}}")
+        lines += [f"\\affiliation{{{aff}}}" for aff in a["affils"]]
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)
+
+
+def _fmt_jcap(authors, index):
+    # jcappub labels affiliations with letters
+    if len(index) > 26:
+        raise ValueError("The JCAP format supports at most 26 affiliations.")
+    letters = {aff: string.ascii_lowercase[n - 1] for aff, n in index.items()}
+    lines = []
+    for a in authors:
+        labels = ",".join(sorted(letters[x] for x in a["affils"]))
+        opt = f"[{labels}]" if labels else ""
+        lines.append(f"\\author{opt}{{{a['name']}}}")
+    lines.append("")
+    lines += [f"\\affiliation[{letters[aff]}]{{{aff}}}" for aff in index]
+    emails = [a["email"] for a in authors if a["email"]]
+    if emails:
+        lines.append("")
+        lines += [f"\\emailAdd{{{e}}}" for e in emails]
+    return "\n".join(lines)
+
+
+def _fmt_generic(authors, index):
+    names = [f"{a['name']}{_sup(a, index)}" for a in authors]
+    if len(names) > 1:
+        head = ", ".join(names[:-1]) + " and " + names[-1]
+    else:
+        head = names[0]
+    insts = [f"$^{{{n}}}$" + aff for aff, n in index.items()]
+    return head + "\n\n" + "\n".join(insts)
+
+
+_RENDERERS = {"mnras": _fmt_mnras, "aanda": _fmt_aanda, "aastex": _fmt_aastex,
+              "revtex": _fmt_revtex, "jcap": _fmt_jcap, "generic": _fmt_generic}
+
+
+def authorlist(source, journal="mnras"):
+    """LaTeX author/affiliation block for a journal, from a CSV file.
+
+    Parameters
+    ----------
+    source : str, Path, or list of dicts
+        Path to a CSV file with columns ``name``, ``affiliations``
+        (";"-separated), ``orcid``, ``email`` — or an equivalent list of
+        dicts. See the module docstring for the format.
+    journal : str
+        Any journal key/alias the package knows (``"mnras"``, ``"aanda"``,
+        ``"apj"``, ``"oja"``, ``"prd"``, ``"jcap"``, ...) or ``"generic"``
+        for a plain numbered-superscript block.
+
+    Returns
+    -------
+    str : LaTeX source to paste into your manuscript.
+
+    Examples
+    --------
+    >>> print(pa.authorlist("authors.csv", journal="aanda"))
+    """
+    from ._core import _resolve
+    key = "generic" if str(journal).lower() == "generic" else _resolve(journal)
+    fmt = _FORMATS[key]
+    authors = _read_authors(source)
+    index = _affiliation_index(authors)
+    header = (f"% Author list generated by plotastro ({key} format)\n"
+              f"% Check addresses/footnotes against the journal template.\n")
+    return header + _RENDERERS[fmt](authors, index)
+
+
+def main(argv=None):
+    """Command-line entry point: ``plotastro-authors authors.csv -j mnras``."""
+    parser = argparse.ArgumentParser(
+        prog="plotastro-authors",
+        description="Generate a journal-ready LaTeX author/affiliation block "
+                    "from a CSV file (columns: Authorname or Firstname/"
+                    "Lastname, Affiliation, ORCID, Email; extra columns are "
+                    "ignored).")
+    parser.add_argument("csv", help="path to the author CSV file")
+    parser.add_argument("-j", "--journal", default="mnras",
+                        help="journal key, e.g. mnras, aanda, apj, oja, prd, "
+                             "jcap, or 'generic' (default: mnras)")
+    parser.add_argument("-o", "--output",
+                        help="write to this .tex file instead of stdout")
+    args = parser.parse_args(argv)
+    try:
+        tex = authorlist(args.csv, journal=args.journal)
+    except (ValueError, OSError) as exc:
+        parser.exit(1, f"error: {exc}\n")
+    if args.output:
+        Path(args.output).write_text(tex + "\n", encoding="utf-8")
+        print(f"wrote {args.output}")
+    else:
+        print(tex)
+
+
+if __name__ == "__main__":
+    main()

plotastro/_colors.py

@@ -0,0 +1,227 @@
+"""Palettes, colour utilities and colour-vision-deficiency checking."""
+
+from __future__ import annotations
+
+import colorsys
+
+import matplotlib.colors as mcolors
+import matplotlib.pyplot as plt
+import numpy as np
+
+from ._core import figsize
+
+# ----------------------------------------------------------------------
+# Palettes
+# ----------------------------------------------------------------------
+
+#: The default colour-blind-friendly cycle, by name (see the README).
+#: First 9: reordered ColorBrewer "Set1" made colour-blind safe;
+#: last 3: light companions from Tableau's Color Blind 10 palette.
+COLORS = {
+    "blue":        "#377eb8",
+    "orange":      "#ff7f00",
+    "green":       "#4daf4a",
+    "pink":        "#f781bf",
+    "brown":       "#a65628",
+    "purple":      "#984ea3",
+    "grey":        "#999999",
+    "red":         "#e41a1c",
+    "yellow":      "#dede00",
+    "lightblue":   "#a2c8ec",
+    "lightorange": "#ffbc79",
+    "lightgrey":   "#ababab",
+}
+
+#: The colours of the default cycle, in order.
+CYCLE = list(COLORS.values())
+
+#: Okabe & Ito (2008) palette — the classic 8-colour scheme designed
+#: for all common types of colour-vision deficiency.
+OKABE_ITO = {
+    "black":      "#000000",
+    "orange":     "#e69f00",
+    "skyblue":    "#56b4e9",
+    "green":      "#009e73",
+    "yellow":     "#f0e442",
+    "blue":       "#0072b2",
+    "vermillion": "#d55e00",
+    "purple":     "#cc79a7",
+}
+
+#: Petroff (2021) 10-colour palette — the CVD-optimised cycle adopted as
+#: matplotlib's "petroff10" style and widely used in particle physics.
+PETROFF10 = {
+    "blue":   "#3f90da",
+    "yellow": "#ffa90e",
+    "red":    "#bd1f01",
+    "grey":   "#94a4a2",
+    "purple": "#832db6",
+    "brown":  "#a96b59",
+    "orange": "#e76300",
+    "tan":    "#b9ac70",
+    "slate":  "#717581",
+    "cyan":   "#92dadd",
+}
+
+#: Light/dark pairs (ColorBrewer "Paired") — ideal for data/model or
+#: before/after pairs: PAIRED["blue"] -> (light, dark). Note this palette
+#: is *not* fully CVD-safe on its own (it contains red and green); pair
+#: it with distinct line styles or markers.
+PAIRED = {
+    "blue":   ("#a6cee3", "#1f78b4"),
+    "green":  ("#b2df8a", "#33a02c"),
+    "red":    ("#fb9a99", "#e31a1c"),
+    "orange": ("#fdbf6f", "#ff7f00"),
+    "purple": ("#cab2d6", "#6a3d9a"),
+    "brown":  ("#ffff99", "#b15928"),
+}
+
+
+def lighten(color, amount=0.5):
+    """Lighten a colour by moving it towards white (0 = unchanged, 1 = white).
+
+    Handy for e.g. filled uncertainty bands under a line of the same hue:
+
+    >>> ax.plot(x, y, color=pa.COLORS["blue"])
+    >>> ax.fill_between(x, lo, hi, color=pa.lighten(pa.COLORS["blue"], 0.7))
+    """
+    h, l, s = colorsys.rgb_to_hls(*mcolors.to_rgb(color))
+    return colorsys.hls_to_rgb(h, l + (1 - l) * amount, s)
+
+
+def darken(color, amount=0.5):
+    """Darken a colour by moving it towards black (0 = unchanged, 1 = black)."""
+    h, l, s = colorsys.rgb_to_hls(*mcolors.to_rgb(color))
+    return colorsys.hls_to_rgb(h, l * (1 - amount), s)
+
+
+# ----------------------------------------------------------------------
+# Colour-vision-deficiency simulation
+# ----------------------------------------------------------------------
+
+# Machado, Oliveira & Fernandes (2009), IEEE TVCG 15(6) — severity-1.0
+# transformation matrices, applied in linear RGB.
+_CVD_MATRICES = {
+    "protanopia": np.array([
+        [0.152286, 1.052583, -0.204868],
+        [0.114503, 0.786281, 0.099216],
+        [-0.003882, -0.048116, 1.051998]]),
+    "deuteranopia": np.array([
+        [0.367322, 0.860646, -0.227968],
+        [0.280085, 0.672501, 0.047413],
+        [-0.011820, 0.042940, 0.968881]]),
+    "tritanopia": np.array([
+        [1.255528, -0.076749, -0.178779],
+        [-0.078411, 0.930809, 0.147602],
+        [0.004733, 0.691367, 0.303900]]),
+}
+
+
+def _srgb_to_linear(c):
+    return np.where(c <= 0.04045, c / 12.92, ((c + 0.055) / 1.055) ** 2.4)
+
+
+def _linear_to_srgb(c):
+    return np.where(c <= 0.0031308, c * 12.92, 1.055 * c ** (1 / 2.4) - 0.055)
+
+
+def simulate_cvd(colors, kind="deuteranopia"):
+    """Simulate how colours appear with a colour-vision deficiency.
+
+    Parameters
+    ----------
+    colors : colour, sequence of colours, or (..., 3/4) float array
+        Anything matplotlib understands (hex strings, names, RGB tuples,
+        an image array from a rendered figure, ...).
+    kind : {"deuteranopia", "protanopia", "tritanopia", "greyscale"}
+        Deficiency to simulate. Deuteranopia and protanopia (red-green)
+        together affect ~5% of male readers; greyscale is what a
+        black-and-white printout shows.
+
+    Returns
+    -------
+    ndarray of RGB(A) values in [0, 1], one row per input colour (or the
+    same shape as an input image array).
+
+    Notes
+    -----
+    Uses the severity-1.0 matrices of Machado et al. (2009), applied in
+    linear RGB — the same model behind most online CVD simulators.
+    """
+    arr = np.asarray(colors, dtype=float) if (
+        isinstance(colors, np.ndarray) and colors.ndim >= 2
+    ) else np.atleast_2d(mcolors.to_rgba_array(colors))
+    if arr.max() > 1.0:  # e.g. uint8 image content passed as float
+        arr = arr / 255.0
+    rgb, alpha = arr[..., :3], arr[..., 3:]
+    lin = _srgb_to_linear(np.clip(rgb, 0, 1))
+    if kind == "greyscale":
+        lum = lin @ np.array([0.2126, 0.7152, 0.0722])
+        lin = np.repeat(lum[..., None], 3, axis=-1)
+    elif kind in _CVD_MATRICES:
+        lin = lin @ _CVD_MATRICES[kind].T
+    else:
+        options = ", ".join(list(_CVD_MATRICES) + ["greyscale"])
+        raise ValueError(f"kind must be one of: {options}; got {kind!r}")
+    out = _linear_to_srgb(np.clip(lin, 0, 1))
+    return np.concatenate([out, alpha], axis=-1) if alpha.size else out
+
+
+def check_colors(palette=None, kinds=("deuteranopia", "protanopia", "greyscale")):
+    """Show a palette next to CVD simulations of it, to verify that the
+    colours stay distinguishable. Returns the figure.
+
+    Parameters
+    ----------
+    palette : dict, list of colours, or None
+        Defaults to the package's colour cycle.
+    kinds : sequence of str
+        Simulations to include (see :func:`simulate_cvd`).
+    """
+    palette = palette if palette is not None else COLORS
+    cols = list(palette.values()) if isinstance(palette, dict) else list(palette)
+    rows = ["original", *kinds]
+    fig, ax = plt.subplots(
+        figsize=figsize("full", journal="mnras", fraction=0.9,
+                        height=0.4 * len(rows) + 0.4))
+    ax.set_axis_off()
+    for i, row in enumerate(rows):
+        y = len(rows) - 1 - i
+        shown = cols if row == "original" else simulate_cvd(cols, row)
+        for j, c in enumerate(shown):
+            ax.add_patch(plt.Rectangle((j, y + 0.12), 0.92, 0.76, color=c))
+        ax.text(-0.15, y + 0.5, row, ha="right", va="center", fontsize=8)
+    ax.set_xlim(-2.2, len(cols))
+    ax.set_ylim(0, len(rows))
+    ax.set_title("Colour-vision-deficiency check")
+    return fig
+
+
+def check_figure(fig=None, kinds=("deuteranopia", "protanopia", "greyscale")):
+    """Render an existing figure and show how it appears under CVD
+    simulations — the final accessibility check before submission.
+
+    Parameters
+    ----------
+    fig : Figure, optional
+        Defaults to the current figure.
+    kinds : sequence of str
+        Simulations to include (see :func:`simulate_cvd`).
+
+    Returns
+    -------
+    The new comparison figure.
+    """
+    fig = fig if fig is not None else plt.gcf()
+    fig.canvas.draw()
+    img = np.asarray(fig.canvas.buffer_rgba(), dtype=float) / 255.0
+    panels = [("original", img)] + [(k, simulate_cvd(img, k)) for k in kinds]
+    n = len(panels)
+    ar = img.shape[0] / img.shape[1]
+    w = 6.5
+    out, axes = plt.subplots(1, n, figsize=(w, ar * w / n * 1.15))
+    for ax, (label, im) in zip(np.atleast_1d(axes), panels):
+        ax.imshow(im)
+        ax.set_axis_off()
+        ax.set_title(label, fontsize=8)
+    return out