plotastro 1.0.0__tar.gz → 1.0.1__tar.gz

{plotastro-1.0.0 → plotastro-1.0.1}/.gitignore

@@ -6,3 +6,6 @@ build/
 *.egg-info/
 .pytest_cache/
 .venv/
+docs/_build/
+docs/_figures/
+docs/tutorial.ipynb

plotastro-1.0.1/.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration — https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/requirements.txt

{plotastro-1.0.0 → plotastro-1.0.1}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.0.1 — 2026-09-01
+
+### Added
+- Documentation site (Sphinx + Furo on Read the Docs) with the rendered
+  tutorial notebook and a full API reference:
+  <https://plotastro.readthedocs.io>.
+
+No changes to the package code itself.
+
 ## 1.0.0 — 2026-09-01
 
 First release as an installable package, `plotastro`.

{plotastro-1.0.0 → plotastro-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plotastro
-Version: 1.0.0
+Version: 1.0.1
 Summary: Publication-quality matplotlib styles and helpers for astronomy journals (MNRAS, A&A, ApJ, OJA, PRD, JCAP, Nature Astronomy)
 Project-URL: Homepage, https://github.com/BehnoodBandi/plotastro
 Project-URL: Issues, https://github.com/BehnoodBandi/plotastro/issues
@@ -66,7 +66,8 @@ pa.savefig("myplot")             # -> myplot.pdf, ready for \includegraphics
 |---|---|
 | ![single-column example](examples/figures/example_column.png) | ![full-width example](examples/figures/example_full.png) |
 
-**Start with the [tutorial notebook](examples/tutorial.ipynb)** — it walks
+**Full documentation: [plotastro.readthedocs.io](https://plotastro.readthedocs.io)** —
+or start with the [tutorial notebook](examples/tutorial.ipynb), which walks
 through every feature with runnable examples.
 
 ## Why this exists
@@ -412,7 +413,7 @@ files (CI checks they stay in sync). Releases: bump the version in
 ## Credits
 
 - Original MNRAS style this grew from:
-  [M. Knabenhans' mplstyle_for_MNRAS](https://github.com/mischakn/mplstyle_for_MNRAS)
+  [M. Knabenhans' mplstyle_for_MNRAS](https://github.com/miknab/mplstyle_for_MNRAS)
 - Colour-blind-friendly Set1 ordering:
   [Thøger Rivera-Thorsen](https://gist.github.com/thriveth/8560036);
   light colours from Tableau *Color Blind 10*

{plotastro-1.0.0 → plotastro-1.0.1}/README.md

@@ -42,7 +42,8 @@ pa.savefig("myplot")             # -> myplot.pdf, ready for \includegraphics
 |---|---|
 | ![single-column example](examples/figures/example_column.png) | ![full-width example](examples/figures/example_full.png) |
 
-**Start with the [tutorial notebook](examples/tutorial.ipynb)** — it walks
+**Full documentation: [plotastro.readthedocs.io](https://plotastro.readthedocs.io)** —
+or start with the [tutorial notebook](examples/tutorial.ipynb), which walks
 through every feature with runnable examples.
 
 ## Why this exists
@@ -388,7 +389,7 @@ files (CI checks they stay in sync). Releases: bump the version in
 ## Credits
 
 - Original MNRAS style this grew from:
-  [M. Knabenhans' mplstyle_for_MNRAS](https://github.com/mischakn/mplstyle_for_MNRAS)
+  [M. Knabenhans' mplstyle_for_MNRAS](https://github.com/miknab/mplstyle_for_MNRAS)
 - Colour-blind-friendly Set1 ordering:
   [Thøger Rivera-Thorsen](https://gist.github.com/thriveth/8560036);
   light colours from Tableau *Color Blind 10*

plotastro-1.0.1/docs/api.md

@@ -0,0 +1,80 @@
+# API reference
+
+Everything is available at the top level:
+
+```python
+import plotastro as pa
+```
+
+## Styles and sizing
+
+```{eval-rst}
+.. autofunction:: plotastro.set_style
+.. autofunction:: plotastro.figsize
+.. autofunction:: plotastro.subplots
+.. autofunction:: plotastro.savefig
+.. autofunction:: plotastro.current_journal
+```
+
+`pa.use(...)` is an alias of {func}`plotastro.set_style`.
+
+## Colours
+
+```{eval-rst}
+.. autofunction:: plotastro.lighten
+.. autofunction:: plotastro.darken
+.. autofunction:: plotastro.simulate_cvd
+.. autofunction:: plotastro.check_colors
+.. autofunction:: plotastro.check_figure
+```
+
+### Palette constants
+
+| name | contents |
+|---|---|
+| `pa.COLORS` | the default 12-colour colour-blind-friendly cycle, by name |
+| `pa.CYCLE` | the same colours as an ordered list |
+| `pa.OKABE_ITO` | Okabe & Ito (2008) 8-colour CVD-safe palette |
+| `pa.PETROFF10` | Petroff (2021) 10-colour CVD-optimised palette |
+| `pa.PAIRED` | light/dark pairs: `pa.PAIRED["blue"] -> (light, dark)` |
+
+## Markers, line styles and labels
+
+```{eval-rst}
+.. autofunction:: plotastro.style_cycler
+.. autofunction:: plotastro.label_panels
+```
+
+| name | contents |
+|---|---|
+| `pa.MARKERS` | marker sequence that stays distinguishable at 4 pt |
+| `pa.LINESTYLES` | named dash patterns beyond matplotlib's built-ins |
+
+## Reference charts
+
+```{eval-rst}
+.. autofunction:: plotastro.show_colors
+.. autofunction:: plotastro.show_markers
+.. autofunction:: plotastro.show_linestyles
+```
+
+## Author lists
+
+```{eval-rst}
+.. autofunction:: plotastro.authorlist
+```
+
+The `plotastro-authors` command-line tool wraps this function; run
+`plotastro-authors --help` for its options.
+
+## Journal data and legacy
+
+```{eval-rst}
+.. autofunction:: plotastro.set_size
+```
+
+| name | contents |
+|---|---|
+| `pa.JOURNALS` | per-journal column/full widths (LaTeX points) and metadata |
+| `pa.GOLDEN` | the golden ratio (default figure aspect), ≈ 0.618 |
+| `pa.STYLE_DIR` | path to the bundled `.mplstyle` files |

plotastro-1.0.1/docs/authors.md

@@ -0,0 +1,78 @@
+# Author lists from a CSV
+
+Assembling the author/affiliation block by hand is error-prone on long
+collaborations. Feed plotastro the author CSV your collaboration already
+maintains — it works with real-world lists exactly as they are:
+
+```text
+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,
+Verdier,Aur\'{e}lien,Aur\'{e}lien Verdier,aurelien.verdier@epfl.ch,False,"EPFL, \'{E}cole polytechnique f\'{e}d\'{e}rale de Lausanne, Chemin des Maillettes, 51, 1290 Versoix, Switzerland",,
+Richard,Johan,Johan Richard,johan.richard@univ-lyon1.fr,False,"CRAL, Centre de Recherche Astrophysique de Lyon, Universit\'{e} de Lyon, 9 avenue Charles Andr\'{e}, 69230 Saint-Genis-Laval, France",0000-0001-5492-1049,
+Loveday,Jon ,Jon Loveday, j.loveday@sussex.ac.uk, False,"Astronomy Centre, University of Sussex, Falmer, Brighton BN1 9QH, UK",0000-0001-5290-8940,
+Brown,Michael,Michael Brown,michael.brown@monash.edu,False,"Monash, School of Physics and Astronomy, Monash University, Wellington Road, Clayton, VIC 3800, Australia",0000-0002-1207-9137,
+```
+
+## What the reader understands
+
+- **Names**: `Authorname` is preferred (alias `name`); if absent, the name
+  is built from `Firstname` + `Lastname`.
+- **Affiliations**: `Affiliation`/`affiliations` — several separated by
+  `;`, or one row per affiliation (repeated author rows are merged).
+  Numbered in order of first appearance and shared between authors
+  automatically.
+- **Optional**: `ORCID` (used where the format supports it) and `Email` —
+  the first author with an email becomes the corresponding author.
+- **Everything else is ignored** (`JoinedAsBuilder`, ...), stray spaces
+  are stripped, and LaTeX already in the file (accents like `\'{e}`)
+  passes through untouched.
+
+## Generating the LaTeX
+
+```python
+import plotastro as pa
+print(pa.authorlist("authors.csv", journal="mnras"))
+```
+
+```latex
+\author[B. Bandi et al.]{
+Behnood Bandi,$^{1}$\thanks{E-mail: b.bandi@sussex.ac.uk}
+Antoine Rocher,$^{2}$
+Aur\'{e}lien Verdier,$^{2}$
+Johan Richard,$^{3}$
+Jon Loveday$^{1}$
+and Michael Brown$^{4}$
+\\
+% List of institutions
+$^{1}$Astronomy Centre, University of Sussex, Falmer, Brighton BN1 9QH, UK\\
+$^{2}$EPFL, \'{E}cole polytechnique f\'{e}d\'{e}rale de Lausanne, Chemin des Maillettes, 51, 1290 Versoix, Switzerland\\
+$^{3}$CRAL, Centre de Recherche Astrophysique de Lyon, Universit\'{e} de Lyon, 9 avenue Charles Andr\'{e}, 69230 Saint-Genis-Laval, France\\
+$^{4}$Monash, School of Physics and Astronomy, Monash University, Wellington Road, Clayton, VIC 3800, Australia
+}
+```
+
+The same CSV works for every journal the package knows:
+
+| `journal=` | output format |
+|---|---|
+| `mnras`, `rasti` | MNRAS `\author[...]{...}` block with superscripts |
+| `aanda` | A&A `\inst{...}` + `\institute{...}` |
+| `apj`, `oja` | AASTeX `\author[orcid]{...}` + `\affiliation`, `\correspondingauthor` |
+| `prd` | REVTeX `\author` + `\email` + `\affiliation` |
+| `jcap` | jcappub lettered `\affiliation[a]` + `\emailAdd` |
+| `generic` | plain numbered-superscript block |
+
+## Command line
+
+A CLI ships with the package, so co-authors who don't use Python can run
+it too:
+
+```bash
+plotastro-authors authors.csv --journal aanda
+plotastro-authors authors.csv -j apj -o authors.tex
+```
+
+The output is a starting point that compiles with the journal's template —
+always diff it against the class file's expectations before submission
+(each output starts with a reminder comment).

plotastro-1.0.1/docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

plotastro-1.0.1/docs/colors.md

@@ -0,0 +1,76 @@
+# Colours
+
+## The default palette
+
+```{image} _figures/palette.png
+:alt: The default colour-blind-friendly cycle
+:width: 85%
+```
+
+The default cycle has 12 colours, all accessible by name via
+`plotastro.COLORS` (e.g. `pa.COLORS["blue"]`), or as matplotlib's
+`"C0"`…`"C11"` shorthands:
+
+- **C0–C8** are a colour-blind-safe re-ordering of the
+  [ColorBrewer](https://colorbrewer2.org) *Set1* qualitative palette
+  (popularised by [Thøger Rivera-Thorsen's CBcycle](https://gist.github.com/thriveth/8560036)).
+  Consecutive colours differ in **lightness as well as hue**, so adjacent
+  lines stay distinguishable under the common deficiencies (deuteranopia,
+  protanopia) *and* in greyscale print; the notorious red–green pair is
+  pushed far apart in the cycle (green is C2, red is C7), so plots with a
+  handful of lines never rely on it.
+- **C9–C11** are light companions (from Tableau's *Color Blind 10*): use
+  them for uncertainty bands, reference curves, or de-emphasised data
+  underneath a saturated line of the same hue.
+
+## Matched shades without transparency
+
+Better for print and EPS than `alpha=` (no colour shifts where elements
+overlap):
+
+```python
+ax.plot(x, y, color=pa.COLORS["blue"])
+ax.fill_between(x, lo, hi, color=pa.lighten(pa.COLORS["blue"], 0.7))
+pa.darken(pa.COLORS["orange"], 0.3)     # the other direction
+```
+
+## More palettes
+
+- `pa.OKABE_ITO` — [Okabe & Ito (2008)](https://jfly.uni-koeln.de/color/),
+  *the* classic CVD-safe recommendation for categorical colours in science;
+- `pa.PETROFF10` — [Petroff (2021)](https://arxiv.org/abs/2107.02270), the
+  CVD-optimised 10-colour cycle used across particle physics;
+- `pa.PAIRED` — light/dark pairs for data/model or before/after
+  comparisons: `pa.PAIRED["blue"]` → `("#a6cee3", "#1f78b4")`.
+
+## Checking accessibility yourself
+
+```{image} _figures/cvd_check.png
+:alt: The default palette under simulated colour-vision deficiencies
+:width: 85%
+```
+
+Don't take the palette's word for it — simulate it (Machado et al. 2009
+model, no extra dependencies):
+
+```python
+pa.check_colors()                 # any palette under deuteranopia/protanopia/greyscale
+pa.check_colors(pa.PAIRED)        # works on your own colour lists/dicts too
+pa.check_figure(fig)              # simulate a whole rendered figure — the
+                                  # final check before submission
+pa.simulate_cvd("#e41a1c", "deuteranopia")   # the raw transform
+```
+
+If two lines merge in any panel, add markers or dash patterns (see
+{doc}`markers`), or pick colours further apart in the cycle. MNRAS
+recommends [Color Oracle](https://colororacle.org) and ColorBrewer for
+exactly this; with plotastro it's built in.
+
+## Colormaps
+
+The styles default to `viridis` (perceptually uniform, CVD-safe). Good
+picks: `viridis`/`magma`/`cividis` for sequential data, `RdBu_r` or
+`coolwarm` for diverging data (red–*blue*, not red–green). Avoid
+`jet`/`rainbow`. For more astro-friendly maps see
+[cmasher](https://cmasher.readthedocs.io) and
+[cmocean](https://matplotlib.org/cmocean/).

plotastro-1.0.1/docs/conf.py

@@ -0,0 +1,72 @@
+"""Sphinx configuration for plotastro's documentation (Read the Docs)."""
+
+import json
+import re
+import shutil
+from importlib.metadata import PackageNotFoundError, version as get_version
+from pathlib import Path
+
+project = "plotastro"
+author = "Behnood Bandi"
+copyright = "2026, Behnood Bandi"
+
+try:
+    release = get_version("plotastro")
+except PackageNotFoundError:
+    release = "1.0.0"
+version = ".".join(release.split(".")[:2])
+
+extensions = [
+    "myst_nb",                # markdown pages + rendered notebooks
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",    # numpy-style docstrings
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+]
+
+myst_enable_extensions = ["colon_fence", "deflist"]
+myst_heading_anchors = 3
+
+# The tutorial notebook is committed already-executed; never re-run it here.
+nb_execution_mode = "off"
+
+exclude_patterns = ["_build", "jupyter_execute", "Thumbs.db", ".DS_Store"]
+
+# Pull the notebook and the reference figures into the docs source tree so
+# the build is self-contained (works identically locally and on RTD).
+_docs = Path(__file__).resolve().parent
+_repo = _docs.parent
+shutil.copytree(_repo / "examples" / "figures", _docs / "_figures",
+                dirs_exist_ok=True)
+
+# The notebook's hand-written table of contents uses Jupyter-style anchors
+# that don't exist in Sphinx (and Furo shows its own sidebar TOC), so strip
+# those lines from the copy rendered here.
+_nb = json.loads((_repo / "examples" / "tutorial.ipynb").read_text())
+for _cell in _nb["cells"]:
+    if _cell["cell_type"] == "markdown":
+        _src = _cell["source"]
+        _lines = _src.splitlines(True) if isinstance(_src, str) else _src
+        _cell["source"] = [l for l in _lines
+                           if not re.match(r"^\d+\.\s+\[.+\]\(#.+\)\s*$", l)]
+(_docs / "tutorial.ipynb").write_text(json.dumps(_nb))
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "none"
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+}
+
+html_theme = "furo"
+html_title = f"plotastro {release}"
+html_theme_options = {
+    "source_repository": "https://github.com/BehnoodBandi/plotastro",
+    "source_branch": "master",
+    "source_directory": "docs/",
+}

plotastro-1.0.1/docs/faq.md

@@ -0,0 +1,46 @@
+# Tweaks and FAQ
+
+**How do I turn the grid off?**
+`pa.set_style("mnras", grid=False)`, or per-axes `ax.grid(False)`.
+
+**How do I override any other setting?**
+`pa.set_style("mnras", **{"font.size": 10})`, or set
+`plt.rcParams[...]` after `set_style` — the styles are ordinary
+matplotlib rcParams underneath.
+
+**I get a "Times New Roman not found" warning.**
+The font list falls back through Times → Nimbus Roman → STIX → DejaVu
+automatically; install `mscorefonts`/STIX to silence it, or ignore it.
+
+**My labels are getting cut off.**
+They shouldn't be — the styles enable `constrained_layout`. If you manage
+layout manually (e.g. `fig.subplots_adjust`), disable it first with
+`plt.rcParams["figure.constrained_layout.use"] = False`.
+
+**What about astronomical images?**
+Use `origin="lower"` in `imshow` (or uncomment `image.origin: lower` in
+the style file), and `ax.grid(False)`.
+
+**Figures look huge/small on my screen.**
+That's just `figure.dpi: 150` for display; the size that lands on disk
+is exact.
+
+**Can I use the styles without any plotastro code?**
+Yes — after `import plotastro` once, `plt.style.use("mnras")` works in any
+code; or copy the `.mplstyle` files from `src/plotastro/styles/` into
+`matplotlib.get_configdir()/stylelib/` and skip the package entirely.
+
+**I used the original mplstyle_for_MNRAS repo — what changed?**
+`plotastro.set_size(...)` reproduces the original `myfigsize.set_size()`
+(including the `mnras`/`mnras_full` width names), and the old
+`MNRAS_Style.mplstyle` is now `plt.style.use("mnras")`.
+
+**A journal wants EPS and my transparency disappeared.**
+EPS has no transparency support. Replace `alpha=` with
+`pa.lighten(colour, amount)` shades — opaque, prints identically, and
+looks the same on screen.
+
+**Which colormap should I use?**
+`viridis` (the default), `magma` or `cividis` for sequential data;
+`RdBu_r`/`coolwarm` for diverging data. Avoid `jet` and `rainbow` — they
+are not perceptually uniform and are hostile to colour-blind readers.

plotastro-1.0.1/docs/index.md

@@ -0,0 +1,91 @@
+# plotastro
+
+**Publication-quality matplotlib figures for astronomy journals.**
+
+One `pip install` gives you journal-matched styles for **MNRAS**, **RASTI**,
+**A&A**, **ApJ/ApJL**, the **Open Journal of Astrophysics**, **PRD/PRL**,
+**JCAP** and **Nature Astronomy** — figures at exactly the right physical
+size, a colour-blind-friendly palette, and helpers that make the tedious
+parts (sizing, panel labels, accessibility checks, author lists, saving)
+one-liners.
+
+```bash
+pip install plotastro
+```
+
+**Simplest usage — no new API to learn.** Importing plotastro registers the
+styles with matplotlib itself; after one `plt.style.use` line you write
+ordinary matplotlib, and the default figure size is already the journal's
+column width:
+
+```python
+import matplotlib.pyplot as plt
+import plotastro                 # just to register the styles
+
+plt.style.use("mnras")           # or "aanda", "apj", "oja", "prd", ...
+fig, ax = plt.subplots()         # plain matplotlib from here on
+```
+
+**With the helpers** (optional, but they make the tedious parts one-liners):
+
+```python
+import plotastro as pa
+
+pa.set_style("mnras")
+fig, ax = pa.subplots()          # one-column figure, golden-ratio height
+ax.plot(x, y, label="model")
+ax.set_xlabel("$x$")
+ax.legend()
+pa.savefig("myplot")             # -> myplot.pdf, ready for \includegraphics
+```
+
+```{image} _figures/example_column.png
+:alt: A single-column example figure
+:width: 55%
+```
+
+## Why plotastro exists
+
+Two problems ruin most paper figures:
+
+1. **Wrong physical size.** If you hand LaTeX a 6-inch figure and it
+   squeezes it into an 84 mm column, every label shrinks by ~50 % and
+   becomes unreadable. The fix: build the figure at its final printed
+   width, then include it with a plain `\includegraphics{fig.pdf}` —
+   no `[width=...]`.
+2. **Inaccessible colours.** ~5 % of male readers have a colour-vision
+   deficiency, and MNRAS's author guidelines explicitly ask for
+   colour-blind-friendly figures. The default matplotlib cycle is not;
+   the one here is — and {func}`plotastro.check_figure` lets you verify it.
+
+The styles share one visual language — Times-like serif fonts at ~9 pt with
+~8 pt tick lettering, inward ticks on all four sides with minors, a subtle
+grid, frameless legends — and differ only in figure width (plus the
+sans-serif fonts Nature requires), so your plots stay **consistent between
+papers** no matter where you submit.
+
+## Where to go next
+
+- {doc}`installation` — install options and requirements
+- {doc}`quickstart` — the five-minute version
+- {doc}`tutorial` — the full hands-on notebook, rendered
+- {doc}`journals` — supported journals and their figure widths
+- {doc}`colors` — the palettes and colour-blindness checking
+- {doc}`markers` — markers, line styles, cyclers and panel labels
+- {doc}`authors` — LaTeX author lists from your collaboration's CSV
+- {doc}`api` — every public function
+
+```{toctree}
+:hidden:
+
+installation
+quickstart
+tutorial
+journals
+colors
+markers
+authors
+api
+faq
+changelog
+```

plotastro-1.0.1/docs/installation.md

@@ -0,0 +1,41 @@
+# Installation
+
+## From PyPI
+
+```bash
+pip install plotastro
+```
+
+The only hard dependency is matplotlib (≥ 3.5). plotastro works with both
+NumPy 1.x and 2.x — CI tests each — and with Python 3.9+. No LaTeX
+installation is required (LaTeX text rendering is optional, see
+{doc}`quickstart`).
+
+## From a clone
+
+```bash
+git clone https://github.com/BehnoodBandi/plotastro
+cd plotastro
+pip install -e ".[dev]"          # editable install + test dependencies
+pytest                           # optional: run the test suite
+```
+
+To run the examples and notebook from a clone:
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+## Styles only, no package
+
+If you just want the `.mplstyle` files, copy them from
+`src/plotastro/styles/` into your matplotlib configuration directory:
+
+```python
+import matplotlib
+print(matplotlib.get_configdir())   # copy the files into <this>/stylelib/
+```
+
+After that, `plt.style.use("mnras")` works in any script without plotastro
+installed. (With the package installed, this step is unnecessary —
+importing plotastro registers the styles automatically.)

plotastro-1.0.1/docs/journals.md

@@ -0,0 +1,51 @@
+# Supported journals
+
+{func}`plotastro.set_style`, {func}`plotastro.figsize` and
+`plt.style.use(...)` accept these keys (aliases in parentheses):
+
+| key | journal | one column | full width |
+|---|---|---|---|
+| `mnras` | Monthly Notices of the RAS | 240.0 pt = 3.32 in | 504.0 pt = 6.97 in |
+| `rasti` | RAS Techniques & Instruments | 240.0 pt = 3.32 in | 504.0 pt = 6.97 in |
+| `aanda` (`a&a`, `aa`) | Astronomy & Astrophysics | 250.4 pt = 3.46 in (88 mm) | 512.2 pt = 7.09 in (180 mm) |
+| `apj` (`apjl`, `aastex`) | The Astrophysical Journal | 242.3 pt = 3.35 in | 513.1 pt = 7.10 in |
+| `oja` | Open Journal of Astrophysics | ≈245.3 pt = 3.39 in | ≈508 pt = 7.03 in |
+| `prd` (`prl`, `revtex`) | Physical Review D | 246.0 pt = 3.40 in | 510.0 pt = 7.06 in |
+| `jcap` | J. Cosmology & Astroparticle Phys. | single-column ≈455 pt = 6.30 in | — |
+| `natastro` (`nature`) | Nature Astronomy (sans-serif!) | 253.2 pt = 3.50 in (89 mm) | 520.7 pt = 7.20 in (183 mm) |
+| `thesis` | A4 thesis text width | 426.8 pt = 5.91 in | — |
+| `beamer` | Beamer slide text width | 307.3 pt = 4.25 in | — |
+
+Widths come from each journal's LaTeX class or author guide. All styles
+share the same fonts, colours, tick and legend settings; only the figure
+width differs — except Nature Astronomy, which switches to the sans-serif
+fonts and smaller (5–7 pt) lettering Nature's figure guide requires.
+
+## Custom documents
+
+For your own document (custom class, thesis template, ...), put
+`\the\columnwidth` or `\the\textwidth` anywhere in the `.tex` body, compile,
+read the value off the page, and pass it directly:
+
+```python
+pa.figsize(width=345.0)          # width in LaTeX points (1 pt = 1/72.27 in)
+```
+
+## Per-journal submission notes
+
+| journal | accepted figure formats | notes |
+|---|---|---|
+| MNRAS / RASTI | EPS preferred, PDF/TIFF fine | ≥ 400 dpi raster, ~8 pt lettering, colour-blind friendly required |
+| A&A | PDF/EPS | figures 88 mm (column) or 170–180 mm (page) wide |
+| ApJ / AAS | PDF/EPS/PNG | vector strongly preferred |
+| OJA | PDF (arXiv-ready) | whatever compiles on arXiv works |
+| PRD / JCAP | PDF/EPS | vector preferred |
+| Nature Astronomy | PDF/EPS/AI | sans-serif fonts, 5–7 pt lettering |
+
+Official guidelines:
+[MNRAS](https://academic.oup.com/mnras/pages/general_instructions) ·
+[A&A](https://www.aanda.org/for-authors) ·
+[AAS Journals](https://journals.aas.org/graphics-guide/) ·
+[OJA](https://astro.theoj.org/site/instructions) ·
+[APS](https://journals.aps.org/authors) ·
+[Nature](https://www.nature.com/nature/for-authors/formatting-guide)

plotastro-1.0.1/docs/markers.md

@@ -0,0 +1,73 @@
+# Markers, line styles and panel labels
+
+## Markers
+
+```{image} _figures/markers.png
+:alt: The marker reference chart
+:width: 85%
+```
+
+`plotastro.MARKERS = ["o", "s", "^", "D", "v", "p", "*", "X"]` — filled
+shapes that survive shrinking to 4 pt. Conventions worth knowing:
+
+| marker | typical use in astro figures |
+|---|---|
+| `"o"` `"s"` `"D"` | primary data series |
+| `"^"` / `"v"` | **lower / upper limits** (readers expect this) |
+| `"*"` `"p"` | highlight special objects (the Sun, a best-fit point) |
+| `"x"` `"+"` | thin crosses — dense scatter plots, since they don't occlude |
+| `"."` | huge point clouds (use `ms=1`–`2`, or better, rasterized hexbin) |
+
+Useful tricks: `markevery=7` thins markers on dense curves; `mfc="none"`
+(hollow markers) keeps overlapping datasets readable; `ms=` and `mew=`
+control size and edge width.
+
+## Line styles
+
+```{image} _figures/linestyles.png
+:alt: The named line-style reference chart
+:width: 85%
+```
+
+Beyond matplotlib's `"-"`, `"--"`, `":"`, `"-."`, the dict
+`plotastro.LINESTYLES` provides named dash tuples of the form
+`(offset, (on, off, ...))` in points:
+
+```python
+ax.plot(x, y, ls=pa.LINESTYLES["long dash"])       # (0, (9, 3))
+ax.plot(x, y, ls=(0, (4, 1, 1, 1)))                # or roll your own
+```
+
+Guidelines: keep to ≤ 4 distinct dash patterns per panel (more becomes
+noise); use solid for data / the headline result and dashes/dots for models
+and references; MNRAS explicitly warns against triple-dot-dashed lines.
+
+## Redundant encoding — the cycler
+
+Colour should never be the *only* difference between curves.
+{func}`plotastro.style_cycler` advances colour, marker and/or line style
+**in step**, so every series is unique in two or three channels at once
+(and survives greyscale printing):
+
+```{image} _figures/redundant_encoding.png
+:alt: Lines distinguished by colour, marker and dash pattern simultaneously
+:width: 55%
+```
+
+```python
+ax.set_prop_cycle(pa.style_cycler(markers=True))              # one axes
+ax.set_prop_cycle(pa.style_cycler(linestyles=True, markers=True))
+plt.rc("axes", prop_cycle=pa.style_cycler(markers=True))      # everywhere
+```
+
+## Panel labels
+
+Journals want multi-panel figures labelled (a), (b), (c)… —
+{func}`plotastro.label_panels` does it in one line, in reading order:
+
+```python
+fig, axes = pa.subplots(2, 2, width="full")
+pa.label_panels(axes)                                    # (a) (b) (c) (d)
+pa.label_panels(axes, loc="outside", fmt="{}", fontweight="bold")  # Nature style
+pa.label_panels(axes, uppercase=True, loc="lower right") # (A) ... bottom-right
+```

plotastro-1.0.1/docs/quickstart.md

@@ -0,0 +1,99 @@
+# Quickstart
+
+## Two ways to use plotastro
+
+**Plain matplotlib** — importing plotastro registers the styles with
+matplotlib, so this is the entire integration:
+
+```python
+import matplotlib.pyplot as plt
+import plotastro
+
+plt.style.use("mnras")
+fig, ax = plt.subplots()         # already MNRAS column-sized
+```
+
+**With the helpers** — journal-aware sizing and saving:
+
+```python
+import plotastro as pa
+
+pa.set_style("mnras")            # pa.use(...) is an alias
+fig, ax = pa.subplots()
+ax.plot(x, y, label="model")
+ax.set_xlabel("$x$")
+ax.legend()
+pa.savefig("myplot")             # -> myplot.pdf
+```
+
+Then in LaTeX, include the figure **without any scaling** — that is the
+whole point (the fonts come out exactly as designed):
+
+```latex
+\begin{figure}
+    \includegraphics{myplot.pdf}   % no [width=...] needed!
+    \caption{...}
+\end{figure}
+```
+
+## Figure sizing
+
+{func}`plotastro.figsize` knows the column and full text widths of each
+journal (see {doc}`journals`):
+
+```python
+pa.figsize("column")                  # one column, golden-ratio height
+pa.figsize("full")                    # full text width
+pa.figsize("column", fraction=0.5)    # half a column
+pa.figsize("column", aspect=1)        # square panel (aspect = height/width)
+pa.figsize("column", journal="aanda") # size for a specific journal
+pa.figsize(345.0)                     # any width in LaTeX points
+```
+
+{func}`plotastro.subplots` takes the same arguments *plus* everything
+`plt.subplots` accepts, and scales the height with the grid so each panel
+keeps its aspect:
+
+```python
+fig, ax   = pa.subplots()                          # 1 panel, one column
+fig, axes = pa.subplots(2, 2, width="full")        # 2x2 grid, full width
+fig, axes = pa.subplots(1, 2, width="full", aspect=0.75, sharey=True)
+```
+
+## Overriding the style
+
+```python
+pa.set_style("mnras", grid=False)                  # no grid
+pa.set_style("mnras", **{"font.size": 10})         # any rcParam
+```
+
+## LaTeX text rendering
+
+By default the styles use matplotlib's built-in *mathtext* with STIX fonts —
+Times-compatible maths that works everywhere, with no LaTeX required. For
+pixel-perfect agreement with your manuscript:
+
+```python
+pa.set_style("mnras", usetex=True)   # needs latex + dvipng + ghostscript
+```
+
+This loads the `newtx` Times fonts (matching the MNRAS/A&A house font), or
+Helvetica for Nature Astronomy. Develop with `usetex=False`, flip it on for
+the final version — LaTeX rendering is slow.
+
+## Saving figures
+
+The styles bake in submission-friendly defaults: **PDF** output, 450 dpi for
+rasterised elements, tight bounding box, and TrueType font embedding
+(`pdf.fonttype: 42`, so no Type-3 font rejections from submission systems).
+
+```python
+pa.savefig("figure1")                              # figure1.pdf
+pa.savefig("figure1", formats=("pdf", "png"))      # + a PNG for slides
+pa.savefig("figure1", fig=fig, dpi=600)            # extra options pass through
+```
+
+If a journal insists on EPS, note EPS has **no transparency** — replace
+`alpha=` with {func}`plotastro.lighten` shades (a good habit anyway).
+
+For the full walk-through with plots, see the {doc}`tutorial`.

plotastro-1.0.1/docs/requirements.txt

@@ -0,0 +1,5 @@
+# Documentation build requirements (Read the Docs installs these).
+sphinx>=7,<9
+furo
+myst-nb>=1.1
+sphinx-copybutton

{plotastro-1.0.0 → plotastro-1.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plotastro"
-version = "1.0.0"
+version = "1.0.1"
 description = "Publication-quality matplotlib styles and helpers for astronomy journals (MNRAS, A&A, ApJ, OJA, PRD, JCAP, Nature Astronomy)"
 readme = "README.md"
 license = { text = "MIT" }