rootfig 0.1.0__tar.gz → 0.2.1__tar.gz

{rootfig-0.1.0 → rootfig-0.2.1}/.gitignore

@@ -9,6 +9,7 @@ build/
 .ruff_cache/
 .coverage
 coverage.xml
+junit.xml
 htmlcov/
 site/
 *.root

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

@@ -26,8 +26,10 @@ uv build && uvx twine check dist/*     # packaging
 ```
 
 CI runs all of these on Python 3.12, 3.13 and 3.14 (Linux), plus macOS
-on 3.13. Tests that use ROOT's tutorial files run only when
-`root-config` is available locally and are skipped otherwise; do not add
+on 3.13, and once more with every direct dependency at the minimum version
+declared in `pyproject.toml` (`uv sync --resolution lowest-direct`). Tests
+that use ROOT's tutorial files run only when `root-config` is available
+locally and are skipped otherwise; do not add
 tests that require ROOT or network access.
 
 ## Layout
@@ -87,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
@@ -95,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
 ```
@@ -105,24 +109,29 @@ 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
 
 - Add tests for behaviour changes; unit tests assert histogram contents and
   matplotlib structure. Rendered output is covered by the gallery (below).
-- Update `CHANGELOG.md` under "Unreleased".
 - Run the checks above before pushing; `pre-commit run --all-files` does most
   of it.
 
 ## Releasing
 
-1. Update the version in `src/rootfig/__init__.py` and move the changelog
-   entries under a new heading.
+1. Update the version in `src/rootfig/__init__.py`.
 2. Commit, tag `vX.Y.Z`, push the tag.
-3. The `release.yml` workflow builds the distribution and publishes it to
-   PyPI via Trusted Publishing (configure the publisher on PyPI first:
-   repository `jbeirer/rootfig`, workflow `release.yml`, environment `pypi`).
+3. The `release.yml` workflow builds the distribution, refuses a tag that does
+   not match `rootfig.__version__`, and publishes it to PyPI via Trusted
+   Publishing (configure the publisher on PyPI first: repository
+   `jbeirer/rootfig`, workflow `release.yml`, environment `pypi`).
 
 The documentation is published by the `docs` job of `ci.yml` on every push to
 `main` (`mkdocs gh-deploy` to the `gh-pages` branch). Once, in the repository

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

@@ -1,12 +1,11 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.1.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
 Project-URL: Repository, https://github.com/jbeirer/rootfig
 Project-URL: Issues, https://github.com/jbeirer/rootfig/issues
-Project-URL: Changelog, https://github.com/jbeirer/rootfig/blob/main/CHANGELOG.md
 Author-email: Joshua Falco Beirer <jbeirer@cern.ch>
 License-Expression: MIT
 License-File: LICENSE
@@ -24,12 +23,12 @@ Classifier: Topic :: Scientific/Engineering :: Physics
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: awkward>=2.6
-Requires-Dist: hist>=2.7
-Requires-Dist: matplotlib>=3.10
-Requires-Dist: mplhep>=0.3.50
+Requires-Dist: awkward>=2.8
+Requires-Dist: hist>=2.7.2
+Requires-Dist: matplotlib>=3.11
+Requires-Dist: mplhep>=1.3
 Requires-Dist: numpy>=1.26
-Requires-Dist: uproot>=5.3
+Requires-Dist: uproot>=5.7.4
 Description-Content-Type: text/markdown
 
 # rootfig
@@ -69,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.1.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.1.0 → rootfig-0.2.1}/docs/composable.md

@@ -44,8 +44,12 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   ```
 
   Without a luminosity such samples raise a [`LuminosityError`][rootfig.LuminosityError].
-- `entry_start`/`entry_stop` restrict reading for quick looks at large files.
-- `sample.with_(label="...")` returns a modified copy.
+- `entry_start`/`entry_stop` restrict reading for quick looks at large files
+  (a plot reads every needed branch of every file into memory at once). For a
+  ready-made `FileSource`, give the range to the source itself; passing it to
+  `Sample` afterwards raises a [`SourceError`][rootfig.SourceError].
+- `sample.with_(label="...")` returns a modified copy; replacement values are
+  validated like constructor arguments.
 
 Passing a list of files to `plot()` creates one sample per file. To merge
 several files into *one* sample, use a glob or a `Sample`.
@@ -67,7 +71,8 @@ met = rf.Variable(
   `"robust"` (ignores far outliers such as `-999` sentinels).
 - `label` and `unit` form the axis label `label [unit]`; the unit also appears
   in the automatic y label (`Events / 4 GeV`).
-- `name` is used for file names by `Plot.save(directory)`.
+- `name` is used for file names by `Plot.save(directory)`; it must be a plain
+  file stem (no path separators).
 
 `bins`, `range`, `xlabel` and `unit` given to `plot()` override the variable.
 

{rootfig-0.1.0 → rootfig-0.2.1}/docs/ecosystem.md

@@ -54,6 +54,9 @@ would do to a matplotlib figure, you can do to `Plot.fig` and `Plot.ax`.
 - You already have flat NumPy columns or `boost-histogram` objects and want
   rich comparison panels: [plothist](https://plothist.readthedocs.io).
 - You need a full columnar analysis framework with lazy, distributed
-  processing: [coffea](https://coffeateam.github.io/coffea/).
+  processing: [coffea](https://coffeateam.github.io/coffea/). rootfig reads
+  every branch a plot needs from every file into memory at once (only the
+  required branches, optionally an entry range), which suits quick looks and
+  moderate ntuples, not multi-terabyte datasets.
 - You want to build fit templates and workspaces: [cabinetry](https://cabinetry.readthedocs.io).
 - You want a quick terminal look at a branch: [histoprint](https://github.com/scikit-hep/histoprint).

{rootfig-0.1.0 → rootfig-0.2.1}/docs/expressions.md

@@ -16,9 +16,11 @@ syntax evaluated with NumPy/Awkward semantics over the branches of the tree.
 | Constants | `pi`, `e`, `inf`, `nan`, `True`, `False` |
 
 `and`, `or`, `not` and chained comparisons are rewritten to element-wise
-operations, so they work on arrays. Attribute access, lambdas,
-comprehensions, string literals and calls to anything but the functions
-below are rejected at parse time with an [`ExpressionError`][rootfig.ExpressionError].
+operations, so they work on arrays. Dotted names such as
+`ReconstructedParticles.momentum.x` are read as one branch name (see below);
+any other attribute access, lambdas, comprehensions, string literals and calls
+to anything but the functions below are rejected at parse time with an
+[`ExpressionError`][rootfig.ExpressionError].
 An unknown branch raises [`MissingBranchError`][rootfig.MissingBranchError]
 with close-match suggestions.
 

{rootfig-0.1.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.1.0 → rootfig-0.2.1}/docs/plotting.md

@@ -43,19 +43,32 @@ dataset scaled to the full one, for instance).
 Variances are scaled consistently. Flow bins scale with the same factor; for
 `"width"` and `"density"` they are divided by the width of the neighbouring
 visible bin. Plain `hist.Hist` objects with a count storage passed to
-`plot_histograms` are converted to `Weight` storage first.
+`plot_histograms` are converted to `Weight` storage first. If such a histogram
+was filled with weights (or rescaled) its sum of squared weights is lost, and
+rootfig refuses it with a `ValueError` rather than invent uncertainties; pass
+`assume_poisson=True` to use the absolute bin contents as variances (with a
+warning), or fill with `hist.storage.Weight()` in the first place.
+
+The rescaling modes divide by the signed sum of the visible bins: a histogram
+dominated by negative weights still sums to the target, its shape flips sign,
+and a warning says so. An empty histogram, or one whose positive and negative
+weights cancel exactly, is left unchanged with a warning and keeps the plain
+`Events` label (`Histogram.normalization` stays `None`).
 
 ## Ratio panel
 
 `ratio=True` adds a lower panel sharing the x axis:
 
 - with a stack: data / total MC, error bars from the data, grey band for the
-  MC statistical uncertainty (`ratio_uncertainty="numerator"`);
-- with data and overlaid samples: data / first sample;
-- otherwise: every sample / the first sample, uncertainties of both
+  MC statistical uncertainty (`ratio_uncertainty="numerator"`); a stacked
+  ratio needs an `observed=` sample;
+- with data and overlaid samples: data / the first non-data sample (only the
+  data appears in the panel);
+- otherwise: every further sample / the first sample, uncertainties of both
   propagated in quadrature (`ratio_uncertainty="propagate"`).
 
-`ratio="Background"` picks the reference by label.
+`ratio="Background"` picks the reference by label; all other histograms, data
+included, are divided by it.
 
 `ratio="significance"` (or `"s/sqrt(b)"`, `"s/sqrt(s+b)"`) draws a
 **significance panel** instead: per bin, the signal over the square root of
@@ -66,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`).
 
@@ -113,8 +129,18 @@ computed values are returned in `Plot.ratios` as
   `(main, ratio)` for ratio plots), so several rootfig plots can share a figure.
 - `save="file.pdf"` saves immediately; `Plot.save(path)` accepts a directory
   (file named after the variable) and `formats=["pdf", "png"]`.
+- Figures use matplotlib's constrained layout, so labels, legends and colour
+  bars fit inside the canvas and a saved file has exactly the `figsize`
+  dimensions: 1D, 2D and ratio plots of one size share one shape. Figures
+  drawn into your own `ax` are saved with a tight bounding box instead.
+- Fonts are fixed on the figure when it is made, so saving or displaying it
+  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
 
@@ -126,6 +152,8 @@ rf.correlation(sample, ["MET", "nJet", "HT"], selection="nJet >= 2", percent=Tru
 `rf.plot2d` options: `logz`, `logx`, `logy`, `cmap` (any matplotlib colour
 map, default `viridis`), `colorbar=False`, `zlabel` (default `Events` or the
 normalisation), `normalize`, `title`, `text`, `style`, `figsize`, `ax`, `save`.
+The figure has the same size as a 1D plot; the colour bar takes its space from
+the axes.
 
 `rf.correlation` options: `labels` (tick labels, default the variable labels),
 `percent=True` (integer percentages instead of two-decimal coefficients),
@@ -168,7 +196,9 @@ Negative weights (NLO samples) can make a weighted variance negative or an
 efficiency leave `[0, 1]`. rootfig then reports `nan` for the standard
 deviation, the profile error or the confidence interval (with a warning for
 efficiencies) rather than a made-up uncertainty; means, yields and histogram
-contents are unaffected.
+contents are unaffected. Bins whose total weight is negative keep their mean
+or efficiency (the plain ratio) but get no uncertainty; bins whose weights
+cancel to exactly zero count as empty (`nan`).
 
 ## Cut flows
 
@@ -183,6 +213,10 @@ table.get("ZH").efficiencies  # relative to the previous step
 table.get("ZH").absolute_efficiencies
 ```
 
+Step efficiencies are plain ratios of weighted yields (`nan` after a zero
+yield). With signed (NLO) weights a yield can be negative and a ratio can lie
+outside `[0, 1]`; it is reported as is.
+
 Cuts apply cumulatively; a sample's own selection is the first row. Per-object
 cuts pass an event when any object passes. `weight`, `lumi` and `nonfinite`
 work as in `plot()`: events with a missing or non-finite weight are excluded