rootfig 0.2.0__tar.gz → 0.2.1__tar.gz

{rootfig-0.2.0 → rootfig-0.2.1}/CONTRIBUTING.md

@@ -89,7 +89,9 @@ f.Close()
 
 ## Figures and the gallery
 
-`examples/gallery.py` is both the showcase and the image-regression suite. Each
+The `examples/gallery` package is both the showcase and the image-regression
+suite: `__init__.py` holds the shared `define()` block and the examples, `data.py`
+writes the toy files and `registry.py` extracts the source shown in the docs. Each
 example is a small function returning a `Plot`; `docs/gallery.md` shows every
 figure next to that function's source (a MkDocs hook, `docs/hooks/gallery.py`),
 and `tests/test_gallery.py` renders all of them and, with `--mpl`, compares
@@ -97,7 +99,7 @@ them pixel-wise (pytest-mpl, RMS tolerance 2) against `docs/images/gallery/`.
 Those PNGs are therefore the documentation images *and* the baselines.
 
 ```bash
-MPLBACKEND=Agg uv run python examples/gallery.py          # look at examples/out/*.png
+MPLBACKEND=Agg uv run python examples/gallery             # look at examples/out/*.png
 uv run pytest tests/test_gallery.py --mpl                 # compare against the baselines
 uv run pytest tests/test_gallery.py --mpl-generate-path=docs/images/gallery   # accept changes
 ```
@@ -107,7 +109,13 @@ them by eye, and commit them with the code. CI compares on Linux only (fonts
 differ elsewhere) and, when a comparison fails, uploads an HTML report with
 baseline, result and difference images as the `mpl-results-*` artifact. To add
 an example, register a function with `@example(name, title)` and give it a
-docstring; the test suite fails until its baseline image exists.
+docstring; the test suite fails until its baseline image exists. Its parameters
+are attribute names of `Dataset`, it runs inside the directory holding the toy
+files (so name them `"signal.root"`, never through a variable), and the hook
+prints only the body (blank lines and comments included) — write it as a user
+would. Put an object into `define()` — the *Setup* block of the docs page — only
+when several examples use it; anything a single example needs belongs in that
+example.
 
 ## Pull requests
 

{rootfig-0.2.0 → rootfig-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.2.0
+Version: 0.2.1
 Summary: Publication-quality figures straight from ROOT trees, without ROOT: uproot + Awkward + hist + mplhep with a TTree::Draw-like API.
 Project-URL: Homepage, https://github.com/jbeirer/rootfig
 Project-URL: Documentation, https://github.com/jbeirer/rootfig#readme
@@ -68,7 +68,7 @@ rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=
 
 These and a dozen more figures, each next to the code that made it, are in the
 [gallery](https://jbeirer.github.io/rootfig/gallery/). All of them come from
-[`examples/gallery.py`](examples/gallery.py), which writes toy ROOT files and
+[`examples/gallery`](examples/gallery/__init__.py), which writes toy ROOT files and
 draws every example in a few seconds; the same figures are pixel-compared in CI.
 
 ## Installation

{rootfig-0.2.0 → rootfig-0.2.1}/README.md

@@ -35,7 +35,7 @@ rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=
 
 These and a dozen more figures, each next to the code that made it, are in the
 [gallery](https://jbeirer.github.io/rootfig/gallery/). All of them come from
-[`examples/gallery.py`](examples/gallery.py), which writes toy ROOT files and
+[`examples/gallery`](examples/gallery/__init__.py), which writes toy ROOT files and
 draws every example in a few seconds; the same figures are pixel-compared in CI.
 
 ## Installation

{rootfig-0.2.0 → rootfig-0.2.1}/docs/gallery.md

@@ -1,33 +1,40 @@
 # Gallery
 
 Every figure on this page is made by
-[`examples/gallery.py`](https://github.com/jbeirer/rootfig/blob/main/examples/gallery.py).
+[`examples/gallery`](https://github.com/jbeirer/rootfig/blob/main/examples/gallery/__init__.py).
 The script writes a toy dataset (three simulated processes and one "observed"
-sample with muons, jets and event-level quantities, as `TTree`s) and runs all
-examples in a few seconds:
+sample with muons, jets and event-level quantities, as `TTree`s) into a
+directory and runs all examples there in a few seconds:
 
 ```bash
-python examples/gallery.py            # figures end up in examples/out/
+python examples/gallery               # everything ends up in examples/out/
 ```
 
 The code next to each figure is the source of that example, and the image is
 the reference picture the test suite compares against, so what you see is what
-the current release draws.
+the current release draws. File names such as `signal.root` are those toy
+files, relative to that directory, and every example assumes
 
 ```python
-import matplotlib.pyplot as plt
-import numpy as np
-
 import rootfig as rf
 ```
 
+<!-- gallery: quick -->
+
 ## Setup
 
-The examples share a few definitions, made once (`out` is the directory with
-the toy files). Everything below is optional: plain strings work everywhere.
+Plain strings and `(bins, low, high)` tuples are accepted everywhere, as the
+one-liner shows. Once you draw more than one plot it pays to name the pieces:
+`Sample`, `Variable`, `Cut` and `Style` are small frozen dataclasses (see
+[Samples, variables, cuts and styles](composable.md)). The rest of this page
+shares four samples, three variables and one style, defined once:
 
 <!-- gallery-setup -->
 
+Anything a single example needs is defined inside that example, so every block
+below is complete given the names above (plus `matplotlib.pyplot as plt` and
+`numpy as np` where they appear).
+
 <!-- gallery -->
 
 ## Beyond figures
@@ -38,21 +45,20 @@ The same inputs feed tables and arrays:
 # entries, mean, std, sem, skewness, min, max per sample and variable
 print(rf.summarize(mc, ["MET", "Muon_pt"], selection="nMuon > 0"))
 
-# a cut flow: yields at a luminosity, raw counts and step efficiencies per sample
+# a cut flow: yields, raw counts and step efficiencies per sample
 print(
     rf.cutflow(
-        [zh, ww, zz],
+        mc,
         ["nMuon >= 2", rf.Cut("MET > 50", label="MET > 50 GeV"), "any(Jet_btag > 0.8)"],
-        lumi="10.8 ab^-1",
     )
 )
 
 # evaluated expressions as an Awkward record array
-events = rf.load(sig, ["MET", "count(Muon_pt)", "first(Muon_pt)"], selection="nJet >= 2")
+events = rf.load(signal, ["MET", "count(Muon_pt)", "first(Muon_pt)"], selection="nJet >= 2")
 events["MET"]
 
 # a plain hist.Hist to feed into your own code
-h = rf.histogram(sig, "MET", bins=(40, 0, 400), selection="nJet >= 2")
+h = rf.histogram(signal, "MET", bins=(40, 0, 400), selection="nJet >= 2")
 ```
 
 Cuts compose with `&`, `|` and `~`, carry optional labels, and combine with

rootfig-0.2.1/docs/hooks/gallery.py

@@ -0,0 +1,98 @@
+"""MkDocs hook that fills ``docs/gallery.md`` from the ``examples/gallery`` package.
+
+Two kinds of marker are expanded when the page is rendered:
+
+``<!-- gallery-setup -->``
+    the body of ``define()``: the samples, variables and style shared by the
+    examples;
+``<!-- gallery -->`` / ``<!-- gallery: name ... -->``
+    one section per example with its title, description, image
+    (``docs/images/gallery/<name>.png``) and the source of the example
+    function. A marker naming examples renders exactly those, so a few can be
+    shown before the setup section; a bare marker renders everything that no
+    earlier marker on the page has shown yet, in registration order.
+
+The gallery module is imported, never executed, so building the docs needs no
+data and draws nothing. Because the images are also the baselines of
+``tests/test_gallery.py``, picture and code cannot drift apart.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[2]
+GALLERY_DIR = ROOT / "examples" / "gallery"
+SETUP_MARKER = "<!-- gallery-setup -->"
+GALLERY_MARKER = re.compile(r"<!-- gallery(?::\s*(?P<names>[\w\s,]+?))?\s*-->")
+
+
+def _load_gallery(name: str = "rootfig_gallery_docs") -> ModuleType:
+    """Import ``examples/gallery`` as a fresh package, without ``examples/`` on ``sys.path``.
+
+    Every call re-executes the package (``mkdocs serve`` renders the page on each
+    rebuild), so its submodules are evicted from ``sys.modules`` first: a cached
+    ``registry`` would keep its ``EXAMPLES`` list and the re-run decorators would
+    register every example a second time.
+    """
+    for cached in [m for m in sys.modules if m == name or m.startswith(f"{name}.")]:
+        del sys.modules[cached]
+    spec = importlib.util.spec_from_file_location(
+        name, GALLERY_DIR / "__init__.py", submodule_search_locations=[str(GALLERY_DIR)]
+    )
+    if spec is None or spec.loader is None:
+        msg = f"cannot load {GALLERY_DIR}"
+        raise RuntimeError(msg)
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def render_section(gallery: ModuleType, example: Any) -> str:
+    """Markdown for one example: heading, description, image, code."""
+    code = gallery.body_source(example.func)
+    return (
+        f"## {example.title}\n\n"
+        f"{example.description}\n\n"
+        f'![{example.title}](images/gallery/{example.name}.png){{ width="75%" }}\n\n'
+        f"```python\n{code}```\n"
+    )
+
+
+def expand_markers(markdown: str, gallery: ModuleType) -> str:
+    """Replace every gallery marker, each example going to the first marker that asks."""
+    shown: set[str] = set()
+    by_name = {example.name: example for example in gallery.EXAMPLES}
+
+    def replace(match: re.Match[str]) -> str:
+        names = match.group("names")
+        if names is None:
+            wanted = [ex.name for ex in gallery.EXAMPLES if ex.name not in shown]
+        else:
+            asked = names.replace(",", " ").split()
+            unknown = [name for name in asked if name not in by_name]
+            if unknown:
+                msg = f"unknown gallery example(s) {unknown} in {match.group(0)!r}"
+                raise ValueError(msg)
+            # first marker wins: skip what an earlier marker (or this one) already rendered
+            wanted = list(dict.fromkeys(name for name in asked if name not in shown))
+        shown.update(wanted)
+        return "\n".join(render_section(gallery, by_name[name]) for name in wanted)
+
+    return GALLERY_MARKER.sub(replace, markdown)
+
+
+def on_page_markdown(markdown: str, **_: Any) -> str:
+    """Expand the gallery markers (MkDocs ``on_page_markdown`` event)."""
+    if SETUP_MARKER not in markdown and not GALLERY_MARKER.search(markdown):
+        return markdown
+    gallery = _load_gallery()
+    setup = gallery.body_source(gallery.define, returns="omit")
+    markdown = markdown.replace(SETUP_MARKER, f"```python\n{setup}```")
+    return expand_markers(markdown, gallery)

{rootfig-0.2.0 → rootfig-0.2.1}/docs/plotting.md

@@ -79,7 +79,10 @@ the signal. The values are returned as a `Ratio` in `Plot.ratios`.
 
 `ratio_ylim` and
 `ratio_label` override the automatic range (at least 0.5 to 1.5, widened to
-cover the bulk of the points) and label (`Ratio to X` or `Data / MC`). The
+cover the bulk of the points) and label (`Ratio to X` or `Data / MC`). A
+rotated y label is bounded by the height of the short ratio panel, so a long
+one is shrunk and, if that is not enough, wrapped onto two lines; pass a
+shorter `ratio_label` such as `"Ratio"` to keep it at full size. The
 computed values are returned in `Plot.ratios` as
 [`Ratio`][rootfig.Ratio] objects (`values`, `errors`, `band`, `edges`).
 
@@ -134,6 +137,10 @@ computed values are returned in `Plot.ratios` as
   later renders exactly the layout that was computed, in the style's fonts.
 - `Plot.fig`, `Plot.ax`, `Plot.ratio_ax` are plain matplotlib objects;
   `Plot.histograms` wrap the `hist.Hist` objects with labels and statistics.
+- In a notebook the figure is displayed automatically — it is a pyplot figure,
+  flushed by the inline backend at the end of the cell, so `%matplotlib inline`
+  is not needed. End the call with `;` to hide the `Plot` repr, and use
+  `Plot.close()` in loops that make many figures.
 
 ## 2D histograms and correlations