rootfig 0.1.0__tar.gz

rootfig-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+site/
+*.root
+!tests/data/*.root
+.ipynb_checkpoints/
+.DS_Store
+
+# generated example output and pytest-mpl results
+examples/out/
+mpl-results/

rootfig-0.1.0/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to rootfig are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/): until 1.0 the public API may
+change in minor releases, with deprecation warnings where practical.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-11
+
+First release.
+
+### Added
+
+- `rf.plot`: one call from ROOT files (TTree or RNTuple, globs, multiple
+  files) to a styled matplotlib figure, with selections, weights, shared
+  binning, overlays, stacks, observed-data points, normalisation, ratio
+  panels, log axes, flow-bin display, a broken x axis (`xbreak`), legends,
+  statistics boxes and experiment labels.
+- `rf.plot_histograms` for existing `hist.Hist` objects (plain count
+  storages are converted to `Weight` storage; overlays may differ in
+  binning), `rf.plot2d`, `rf.correlation`, `rf.summarize`,
+  `rf.histogram`/`rf.histograms`, `rf.load`, `rf.evaluate`, `rf.ratio`,
+  `rf.log_bins`, `rf.use_style`.
+- `rf.cutflow()`: weighted yields, raw counts and step efficiencies after
+  successive cuts, per sample (`CutflowTable`, `Cutflow`).
+- `rf.efficiency()`: pass/total versus a variable with Wilson intervals
+  (`Efficiency`); `rf.profile()`: mean or standard deviation of `y` in bins
+  of `x` (`Profile`), for resolution plots.
+- Significance panel: `ratio="significance"` / `"s/sqrt(b)"` /
+  `"s/sqrt(s+b)"` or `("s/sqrt(b)", "Signal")`; `rf.significance()`.
+- Luminosity normalisation: `Sample(xsec=..., ngen=...)` plus `lumi=` scales
+  simulated samples to expected yields (`xsec × lumi / ngen`, units in
+  strings such as `"1.2 fb"`, `"10.8 ab^-1"`); `ngen` may name an object in
+  the file (a `TParameter` such as FCCAnalyses' `eventsProcessed`, or a
+  sum-of-weights histogram). `LuminosityError`.
+- `Sample`, `Variable`, `Cut` and `Style` descriptions for composable
+  analysis scripts; `Style.lumi`/`Style.com` accept units and
+  `Style(lumi_unit=..., com_unit=...)` set the defaults for numbers.
+- Expression language in Python syntax with `and`/`or`/`not`, chained
+  comparisons, backtick-quoted and dotted branch names
+  (`ReconstructedParticles.momentum.x`, as podio/EDM4hep files write them),
+  NumPy functions, per-event reductions (`count`, `sum`, `min`, `max`,
+  `mean`, `any`, `all`, `first`, ...) and kinematic helpers `pt`, `p`,
+  `theta`, `costheta`, `eta`, `phi`, `mass` from Cartesian components.
+- Documented and tested per-event/per-object semantics for selections and
+  weights, with explicit errors for ambiguous combinations. Fixed-size
+  collections (`float x[3]` branches, two-dimensional NumPy arrays) follow
+  the per-object rules like variable-length lists. Split TTree branches and
+  nested RNTuple fields are listed and read by their dotted leaf name.
+- Experiment-neutral default style with a 40-colour cycle (`tab10` extended
+  by the `tab20` light companions and `tab20b`/`tab20c`); mplhep styles and
+  labels for ATLAS, CMS, LHCb, ALICE and DUNE via `Style(experiment=...)`.
+- Automatic y headroom accounts for the actual legend, experiment label,
+  statistics box and text sizes, so they never cover a histogram (unless
+  `ylim` sets the upper value).
+- A gallery (`examples/gallery.py`, `docs/gallery.md`) with 20 examples
+  covering the plotting options, each shown next to its code, doubling as an
+  image-regression suite (`tests/test_gallery.py`, pytest-mpl) whose
+  baselines are the documentation images.
+- Lower-layer entry points for callers building on rootfig:
+  `rootfig.selection.prepare`/`boolean_mask`, `rootfig.histograms.fill`,
+  `normalize_hist`, `as_weight_storage`, `read_arrays`, `source_length`,
+  `rootfig.plotting.draw_histograms`, `show_flow_bins`, `fold_flow_bins`.
+
+### Behaviour worth knowing
+
+- `nan`/`inf` values are dropped with a `RootfigWarning`
+  (`nonfinite="error"` raises), also in cut flows; missing values (`None`),
+  missing collections and missing event weights drop the entry or event and
+  are counted separately in `Summary`.
+- Negative weights: a weighted variance that comes out negative gives `nan`
+  for the standard deviation of `Summary` and `Profile` (and the profile
+  error); an efficiency outside `[0, 1]` has `nan` interval bounds and
+  warns. Histogram contents, means and yields are unaffected.
+- `flow="show"` and `flow="sum"` are applied by rootfig before ratios,
+  significances, stack bands and limits are computed, identically for all
+  samples; `normalize="width"`/`"density"` divide flow bins by the
+  neighbouring bin width.
+- Ratios, significances and efficiencies require identical bin edges (up to
+  a millionth of a bin width). `Sample.scale`, `xsec`, `ngen` and `lumi`
+  must be finite. `logx`/`logy` default to the `Variable`'s `log` flag.
+- Requires Python 3.12 and matplotlib 3.10 or newer.
+
+[Unreleased]: https://github.com/jbeirer/rootfig/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jbeirer/rootfig/releases/tag/v0.1.0

rootfig-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,129 @@
+# Contributing to rootfig
+
+Thanks for helping. Issues and pull requests are welcome at
+<https://github.com/jbeirer/rootfig>.
+
+## Development setup
+
+rootfig is managed with [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/jbeirer/rootfig
+cd rootfig
+uv sync --all-groups          # runtime, dev and docs dependencies
+uv run pre-commit install     # optional: run the linters on every commit
+```
+
+## Checks
+
+```bash
+uv run pytest                          # tests (ROOT files are generated on the fly)
+uv run pytest --cov                    # with coverage
+uv run ruff check . && uv run ruff format --check .
+uv run mypy                            # strict type checking of src/
+uv run mkdocs serve                    # documentation preview
+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
+tests that require ROOT or network access.
+
+## Layout
+
+```
+src/rootfig/
+  api.py          plot(), histogram(), load(), ...  (orchestration only)
+  errors.py       exception hierarchy
+  expressions/    parse, validate and evaluate expression strings
+  io/             file and in-memory data sources
+  model/          Sample, Variable, Cut, Style, binning
+  selection/      per-event / per-object semantics -> flat columns
+  histograms/     filling, normalisation, ratios, statistics, pipeline
+  plotting/       matplotlib/mplhep rendering, styles, annotations
+tests/            one module per layer plus end-to-end API tests
+docs/             MkDocs sources
+```
+
+Keep the layers independent: `plotting` must not read files, `selection`
+must not know about matplotlib, and so on. Public functions carry NumPy-style
+docstrings and full type hints.
+
+## Test data
+
+Almost all tests generate their ROOT files with uproot on the fly. The one
+committed file, `tests/data/split_collection.root`, has a split
+`std::vector<struct>` branch and a `TParameter` the way podio/EDM4hep and
+FCCAnalyses write them. uproot cannot write such a file, so it was produced
+with PyROOT (ROOT 6.40) by this script; rerun it only if the layout has to
+change, and keep the file small:
+
+```python
+import ROOT
+
+ROOT.gInterpreter.Declare("""
+struct Vec3 { float x; float y; float z; };
+struct Particle { Vec3 momentum; float energy; int charge; };
+""")
+f = ROOT.TFile("split_collection.root", "RECREATE")
+t = ROOT.TTree("events", "events")
+v = ROOT.std.vector("Particle")()
+t.Branch("ReconstructedParticles", v, 32000, 99)  # split level 99 -> dotted sub-branches
+r = ROOT.TRandom3(1)
+for _ in range(200):
+    v.clear()
+    for _ in range(r.Poisson(3)):
+        p = ROOT.Particle()
+        p.momentum.x, p.momentum.y, p.momentum.z = r.Gaus(0, 20), r.Gaus(0, 20), r.Gaus(0, 20)
+        p.energy = (p.momentum.x**2 + p.momentum.y**2 + p.momentum.z**2) ** 0.5 + 0.1
+        p.charge = -1 if r.Uniform() < 0.5 else 1
+        v.push_back(p)
+    t.Fill()
+ROOT.TParameter("int")("eventsProcessed", 200).Write()
+f.Write()
+f.Close()
+```
+
+## Figures and the gallery
+
+`examples/gallery.py` is both the showcase and the image-regression suite. 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
+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
+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
+```
+
+After any visual change: regenerate the baselines, open the PNGs and check
+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.
+
+## 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.
+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`).
+
+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
+settings, set GitHub Pages to serve from that branch.

rootfig-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Falco Beirer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rootfig-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: rootfig
+Version: 0.1.0
+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
+Keywords: HEP,RNTuple,ROOT,TTree,awkward,histogram,matplotlib,mplhep,plotting,uproot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+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: numpy>=1.26
+Requires-Dist: uproot>=5.3
+Description-Content-Type: text/markdown
+
+# rootfig
+
+**Publication-quality figures straight from ROOT trees, without ROOT.**
+
+`rootfig` is the `TTree::Draw` workflow for the Scientific Python HEP stack:
+give it ROOT files, a tree, an expression, a selection and a weight, and get a
+styled matplotlib figure back in one call. It reads with
+[uproot](https://github.com/scikit-hep/uproot5), computes with
+[Awkward Array](https://github.com/scikit-hep/awkward), fills
+[hist](https://github.com/scikit-hep/hist) histograms and draws with
+[mplhep](https://github.com/scikit-hep/mplhep). It adds the missing glue:
+predictable per-event/per-object selection semantics, weights, shared
+binning across samples, normalisation, ratio panels and good defaults.
+
+[![CI](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml/badge.svg)](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jbeirer/rootfig/branch/main/graph/badge.svg)](https://codecov.io/gh/jbeirer/rootfig)
+[![PyPI](https://img.shields.io/pypi/v/rootfig.svg)](https://pypi.org/project/rootfig/)
+[![Python](https://img.shields.io/pypi/pyversions/rootfig.svg)](https://pypi.org/project/rootfig/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+```python
+import rootfig as rf
+
+rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=50)
+```
+
+<p align="center">
+  <img src="docs/images/gallery/stack_data.png" alt="Stacked simulation with data and a ratio panel" width="48%">
+  <img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="48%">
+</p>
+<p align="center">
+  <img src="docs/images/gallery/object_vs_event.png" alt="Per-object versus per-event selections" width="48%">
+  <img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="48%">
+</p>
+
+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
+draws every example in a few seconds; the same figures are pixel-compared in CI.
+
+## Installation
+
+```bash
+pip install rootfig
+# or
+uv add rootfig
+```
+
+Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
+files are both supported.
+
+## Quick start
+
+```python
+import rootfig as rf
+
+# Overlay two samples, normalised to unity, with a ratio panel.
+rf.plot(
+    ["signal.root", "background.root"],
+    "Muon_pt",
+    tree="events",
+    selection="abs(Muon_eta) < 2.5",
+    weight="event_weight",
+    bins=(50, 0, 200),
+    normalize=True,
+    ratio=True,
+)
+```
+
+For analysis scripts with many samples, variables and plots, describe things
+once and reuse them:
+
+```python
+import rootfig as rf
+
+signal = rf.Sample("sig_*.root", tree="events", label="Signal", weight="mc_weight")
+background = rf.Sample("bkg.root", tree="events", label="Background", weight="mc_weight")
+data = rf.Sample("data.root", tree="events", label="Data", is_data=True)
+
+pt = rf.Variable("Muon_pt", bins=(50, 0, 200), label=r"$p_T^{\mu}$", unit="GeV")
+baseline = rf.Cut("nMuon >= 1") & "abs(Muon_eta) < 2.5"
+style = rf.Style(experiment="ATLAS", status="Internal", lumi=140, com=13.6)
+
+p = rf.plot(
+    [background, signal],
+    pt,
+    observed=data,
+    selection=baseline,
+    stack=True,
+    ratio=True,
+    logy=True,
+    style=style,
+)
+p.ax.set_ylim(top=1e5)  # it is a normal matplotlib Axes
+p.save("muon_pt.pdf")
+```
+
+Everything you get back is a standard object: `p.fig` and `p.ax` are
+matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
+`rf.load(...)` returns Awkward arrays.
+
+## Features
+
+- **One call from files to figure**, reading only the branches the expressions need.
+- **Expressions in Python syntax**: `sqrt(px**2 + py**2)`, `count(Jet_pt) >= 2`,
+  `` `jet1_b-tag` > 0.5 ``, `and`/`or`/`not`, chained comparisons.
+- **Jagged branches done right**: per-object cuts mask objects, per-event
+  cuts drop events, ambiguous combinations raise a clear error instead of
+  silently broadcasting.
+- **Weights**: per-event weights broadcast onto objects, per-object weights,
+  constant scale factors, multiplicative combination of sample and plot weights.
+- **Histograms with uncertainties** (`hist` with `Weight` storage), shared
+  binning across samples, automatic or robust ranges, log bins, flow bins.
+- **Overlays, stacks, data points, ratio panels** with correct error
+  propagation for weighted histograms and a reference-uncertainty band.
+- **Normalisation**: to unity, density, per bin width, or to a number; or to
+  a **luminosity** from cross sections and generated-event counts
+  (`Sample(xsec="0.2 pb", ngen="eventsProcessed")`, `lumi="10.8 ab^-1"`).
+- **Analysis tables and panels**: cut flows with yields and efficiencies,
+  significance panels (S/√B), efficiency-versus-variable plots with binomial
+  intervals, profiles and resolutions.
+- **Experiment-neutral defaults**, with mplhep styles and labels for ATLAS,
+  CMS, LHCb, ALICE and DUNE one keyword away; any other experiment name, GeV
+  and ab⁻¹ work too.
+- **EDM4hep-friendly**: sub-branches of split collections are addressed as
+  `ReconstructedParticles.momentum.x`, with `pt`, `p`, `theta`, `costheta`,
+  `eta`, `phi` and `mass` helpers.
+- **Also**: 2D histograms, summary statistics tables, statistics boxes,
+  correlation matrices, multi-file globs, entry ranges for quick looks.
+
+## Documentation
+
+- [Quick start](docs/quickstart.md)
+- [Expressions and selections](docs/expressions.md)
+- [Samples, variables, cuts and styles](docs/composable.md)
+- [Plotting options](docs/plotting.md)
+- [Relation to uproot, Awkward, hist, mplhep and matplotlib](docs/ecosystem.md)
+
+## Relation to the ecosystem
+
+`rootfig` does not replace any of the libraries it builds on:
+
+| Task | Library | What rootfig adds |
+| --- | --- | --- |
+| Reading ROOT files | uproot | file globs, tree auto-detection, reading only the required branches |
+| Jagged arrays | Awkward Array | the per-event/per-object rules for cuts and weights |
+| Histograms | hist / boost-histogram | shared binning, automatic ranges, normalisation, ratios |
+| Drawing | mplhep + matplotlib | overlays, stacks, ratio panels, labels and legends with good defaults |
+
+If you already have `hist.Hist` objects, `rf.plot_histograms` draws them with
+the same options. If you want the arrays, `rf.load` returns them.
+
+## Development
+
+```bash
+git clone https://github.com/jbeirer/rootfig
+cd rootfig
+uv sync --all-groups
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

rootfig-0.1.0/README.md

@@ -0,0 +1,168 @@
+# rootfig
+
+**Publication-quality figures straight from ROOT trees, without ROOT.**
+
+`rootfig` is the `TTree::Draw` workflow for the Scientific Python HEP stack:
+give it ROOT files, a tree, an expression, a selection and a weight, and get a
+styled matplotlib figure back in one call. It reads with
+[uproot](https://github.com/scikit-hep/uproot5), computes with
+[Awkward Array](https://github.com/scikit-hep/awkward), fills
+[hist](https://github.com/scikit-hep/hist) histograms and draws with
+[mplhep](https://github.com/scikit-hep/mplhep). It adds the missing glue:
+predictable per-event/per-object selection semantics, weights, shared
+binning across samples, normalisation, ratio panels and good defaults.
+
+[![CI](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml/badge.svg)](https://github.com/jbeirer/rootfig/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/jbeirer/rootfig/branch/main/graph/badge.svg)](https://codecov.io/gh/jbeirer/rootfig)
+[![PyPI](https://img.shields.io/pypi/v/rootfig.svg)](https://pypi.org/project/rootfig/)
+[![Python](https://img.shields.io/pypi/pyversions/rootfig.svg)](https://pypi.org/project/rootfig/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+```python
+import rootfig as rf
+
+rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=50)
+```
+
+<p align="center">
+  <img src="docs/images/gallery/stack_data.png" alt="Stacked simulation with data and a ratio panel" width="48%">
+  <img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="48%">
+</p>
+<p align="center">
+  <img src="docs/images/gallery/object_vs_event.png" alt="Per-object versus per-event selections" width="48%">
+  <img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="48%">
+</p>
+
+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
+draws every example in a few seconds; the same figures are pixel-compared in CI.
+
+## Installation
+
+```bash
+pip install rootfig
+# or
+uv add rootfig
+```
+
+Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
+files are both supported.
+
+## Quick start
+
+```python
+import rootfig as rf
+
+# Overlay two samples, normalised to unity, with a ratio panel.
+rf.plot(
+    ["signal.root", "background.root"],
+    "Muon_pt",
+    tree="events",
+    selection="abs(Muon_eta) < 2.5",
+    weight="event_weight",
+    bins=(50, 0, 200),
+    normalize=True,
+    ratio=True,
+)
+```
+
+For analysis scripts with many samples, variables and plots, describe things
+once and reuse them:
+
+```python
+import rootfig as rf
+
+signal = rf.Sample("sig_*.root", tree="events", label="Signal", weight="mc_weight")
+background = rf.Sample("bkg.root", tree="events", label="Background", weight="mc_weight")
+data = rf.Sample("data.root", tree="events", label="Data", is_data=True)
+
+pt = rf.Variable("Muon_pt", bins=(50, 0, 200), label=r"$p_T^{\mu}$", unit="GeV")
+baseline = rf.Cut("nMuon >= 1") & "abs(Muon_eta) < 2.5"
+style = rf.Style(experiment="ATLAS", status="Internal", lumi=140, com=13.6)
+
+p = rf.plot(
+    [background, signal],
+    pt,
+    observed=data,
+    selection=baseline,
+    stack=True,
+    ratio=True,
+    logy=True,
+    style=style,
+)
+p.ax.set_ylim(top=1e5)  # it is a normal matplotlib Axes
+p.save("muon_pt.pdf")
+```
+
+Everything you get back is a standard object: `p.fig` and `p.ax` are
+matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
+`rf.load(...)` returns Awkward arrays.
+
+## Features
+
+- **One call from files to figure**, reading only the branches the expressions need.
+- **Expressions in Python syntax**: `sqrt(px**2 + py**2)`, `count(Jet_pt) >= 2`,
+  `` `jet1_b-tag` > 0.5 ``, `and`/`or`/`not`, chained comparisons.
+- **Jagged branches done right**: per-object cuts mask objects, per-event
+  cuts drop events, ambiguous combinations raise a clear error instead of
+  silently broadcasting.
+- **Weights**: per-event weights broadcast onto objects, per-object weights,
+  constant scale factors, multiplicative combination of sample and plot weights.
+- **Histograms with uncertainties** (`hist` with `Weight` storage), shared
+  binning across samples, automatic or robust ranges, log bins, flow bins.
+- **Overlays, stacks, data points, ratio panels** with correct error
+  propagation for weighted histograms and a reference-uncertainty band.
+- **Normalisation**: to unity, density, per bin width, or to a number; or to
+  a **luminosity** from cross sections and generated-event counts
+  (`Sample(xsec="0.2 pb", ngen="eventsProcessed")`, `lumi="10.8 ab^-1"`).
+- **Analysis tables and panels**: cut flows with yields and efficiencies,
+  significance panels (S/√B), efficiency-versus-variable plots with binomial
+  intervals, profiles and resolutions.
+- **Experiment-neutral defaults**, with mplhep styles and labels for ATLAS,
+  CMS, LHCb, ALICE and DUNE one keyword away; any other experiment name, GeV
+  and ab⁻¹ work too.
+- **EDM4hep-friendly**: sub-branches of split collections are addressed as
+  `ReconstructedParticles.momentum.x`, with `pt`, `p`, `theta`, `costheta`,
+  `eta`, `phi` and `mass` helpers.
+- **Also**: 2D histograms, summary statistics tables, statistics boxes,
+  correlation matrices, multi-file globs, entry ranges for quick looks.
+
+## Documentation
+
+- [Quick start](docs/quickstart.md)
+- [Expressions and selections](docs/expressions.md)
+- [Samples, variables, cuts and styles](docs/composable.md)
+- [Plotting options](docs/plotting.md)
+- [Relation to uproot, Awkward, hist, mplhep and matplotlib](docs/ecosystem.md)
+
+## Relation to the ecosystem
+
+`rootfig` does not replace any of the libraries it builds on:
+
+| Task | Library | What rootfig adds |
+| --- | --- | --- |
+| Reading ROOT files | uproot | file globs, tree auto-detection, reading only the required branches |
+| Jagged arrays | Awkward Array | the per-event/per-object rules for cuts and weights |
+| Histograms | hist / boost-histogram | shared binning, automatic ranges, normalisation, ratios |
+| Drawing | mplhep + matplotlib | overlays, stacks, ratio panels, labels and legends with good defaults |
+
+If you already have `hist.Hist` objects, `rf.plot_histograms` draws them with
+the same options. If you want the arrays, `rf.load` returns them.
+
+## Development
+
+```bash
+git clone https://github.com/jbeirer/rootfig
+cd rootfig
+uv sync --all-groups
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

rootfig-0.1.0/docs/api.md

@@ -0,0 +1,51 @@
+# API reference
+
+## Top level
+
+::: rootfig.plot
+::: rootfig.plot_histograms
+::: rootfig.plot2d
+::: rootfig.histogram
+::: rootfig.histograms
+::: rootfig.load
+::: rootfig.summarize
+::: rootfig.correlation
+::: rootfig.cutflow
+::: rootfig.efficiency
+::: rootfig.profile
+::: rootfig.significance
+::: rootfig.evaluate
+::: rootfig.ratio
+::: rootfig.log_bins
+::: rootfig.use_style
+
+## Descriptions
+
+::: rootfig.Sample
+::: rootfig.Variable
+::: rootfig.Cut
+::: rootfig.Style
+
+## Results
+
+::: rootfig.Plot
+::: rootfig.Histogram
+::: rootfig.Ratio
+::: rootfig.Summary
+::: rootfig.SummaryTable
+::: rootfig.Cutflow
+::: rootfig.CutflowTable
+::: rootfig.Efficiency
+::: rootfig.Profile
+
+## Errors and warnings
+
+::: rootfig.errors
+
+## Lower layers
+
+::: rootfig.io
+::: rootfig.expressions
+::: rootfig.selection
+::: rootfig.histograms
+::: rootfig.plotting