rootfig 0.2.2__tar.gz → 0.4.0__tar.gz

{rootfig-0.2.2 → rootfig-0.4.0}/CONTRIBUTING.md

@@ -36,7 +36,7 @@ tests that require ROOT or network access.
 
 ```
 src/rootfig/
-  api.py          plot(), histogram(), load(), ...  (orchestration only)
+  api/            plot(), histogram(), load(), ...  (orchestration only)
   errors.py       exception hierarchy
   expressions/    parse, validate and evaluate expression strings
   io/             file and in-memory data sources
@@ -90,32 +90,43 @@ f.Close()
 ## Figures and the gallery
 
 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
+suite: `__init__.py` holds the shared `define()` block, the `STYLES` 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`. The
+MkDocs hook `docs/hooks/gallery.py` turns them into the gallery: an overview
+(`docs/gallery/index.md`, a card per example, section by section) and a
+generated page per example with its figure and complete code, one tab per
+style. `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.
+An example whose function takes a `style` is rendered in every entry of
+`STYLES` (the neutral default, ATLAS, CMS, LHCb, ALICE, DUNE) as
+`<name>-<style>.png`, `<name>.png` for the default; every rendering is made
+twice, as shown and inside `rf.dark_theme()` (`-dark`), and the docs pick one
+per palette. Those PNGs are therefore the documentation images *and* the
+baselines. The experiment styles are drawn only when images are compared or
+generated, and `-n auto` runs that on every core.
 
 ```bash
-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
+MPLBACKEND=Agg uv run python examples/gallery               # look at examples/out/*.png
+MPLBACKEND=Agg uv run python examples/gallery --style CMS   # ... in another style
+uv run pytest tests/test_gallery.py --mpl -n auto           # compare against the baselines
+uv run pytest tests/test_gallery.py -n auto --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. 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.
+an example, register a function with `@example(name, title, section=...)` and
+give it a docstring; the test suite fails until its baseline images exist. Its
+parameters are attribute names of `Dataset`, plus `style` when the figure should
+be shown in every style (pass it on as `style=style`; leave it out when a style
+is the point of the example or the figure goes into axes of your own). 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 example pages — only when several examples use it;
+anything a single example needs belongs in that example.
 
 ## Pull requests
 

{rootfig-0.2.2 → rootfig-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.2.2
+Version: 0.4.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://jbeirer.github.io/rootfig/
@@ -31,22 +31,35 @@ Requires-Dist: numpy>=1.26
 Requires-Dist: uproot>=5.7.4
 Description-Content-Type: text/markdown
 
-# rootfig
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jbeirer/rootfig/main/.github/assets/rootfig-logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jbeirer/rootfig/main/.github/assets/rootfig-logo-light.svg">
+    <img src="https://raw.githubusercontent.com/jbeirer/rootfig/main/.github/assets/rootfig-logo-light.svg" alt="rootfig" width="560">
+  </picture>
+</p>
 
-**Publication-quality figures straight from ROOT trees, without ROOT.**
+<p align="center">
+  <strong>Publication-quality figures straight from ROOT trees, without ROOT.</strong>
+</p>
 
-[![Docs](https://img.shields.io/badge/docs-online-blue)](https://jbeirer.github.io/rootfig/)
-[![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)
+<p align="center">
+  <a href="https://jbeirer.github.io/rootfig/">Documentation</a> ·
+  <a href="https://jbeirer.github.io/rootfig/gallery/">Gallery</a> ·
+  <a href="https://jbeirer.github.io/rootfig/quickstart/">Quick start</a>
+</p>
 
-**[Documentation](https://jbeirer.github.io/rootfig/) ·
-[Gallery](https://jbeirer.github.io/rootfig/gallery/) ·
-[Quick start](https://jbeirer.github.io/rootfig/quickstart/)**
+<p align="center">
+  <a href="https://jbeirer.github.io/rootfig/"><img src="https://img.shields.io/badge/docs-online-blue" alt="Documentation"></a>
+  <a href="https://doi.org/10.5281/zenodo.22726311"><img src="https://zenodo.org/badge/1366702602.svg" alt="DOI"></a>
+  <a href="https://github.com/jbeirer/rootfig/actions/workflows/ci.yml"><img src="https://github.com/jbeirer/rootfig/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/jbeirer/rootfig"><img src="https://codecov.io/gh/jbeirer/rootfig/branch/main/graph/badge.svg" alt="codecov"></a>
+  <a href="https://pypi.org/project/rootfig/"><img src="https://img.shields.io/pypi/v/rootfig.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/rootfig/"><img src="https://img.shields.io/pypi/pyversions/rootfig.svg" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
 
-Go from ROOT files to a styled figure in one call. Choose a variable, add a
+Go from a ROOT file to a styled figure in one call. Choose a variable, add a
 selection, and plot:
 
 ```python
@@ -57,20 +70,23 @@ rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=
 
 Start with a single distribution; add samples, weights, stacks and ratio
 panels as your analysis grows. Every plot gives you a matplotlib figure to
-customise and save. No ROOT installation required.
+customise and save.
 
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/stack_data.png" alt="Stacked simulation with data and a ratio panel" width="48%"></a>
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/log_axes/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/log_axes-dark.png"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/hist2d/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/hist2d-dark.png"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></picture></a>
 </p>
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/object_vs_event.png" alt="Per-object versus per-event selections" width="48%"></a>
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/xbreak_ratio/#atlas"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/xbreak_ratio-atlas-dark.png"><img src="docs/images/gallery/xbreak_ratio-atlas.png" alt="Broken x axis with a ratio panel" width="46%"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/luminosity/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/luminosity-dark.png"><img src="docs/images/gallery/luminosity.png" alt="FCC-ee stack scaled to luminosity with a significance panel" width="43%"></picture></a>
 </p>
 
 **[Explore the gallery →](https://jbeirer.github.io/rootfig/gallery/)**
 See each figure alongside the code that makes it, from simple overlays to
-stacked data/MC comparisons, broken axes and 2D histograms.
+stacked data/MC comparisons, broken axes and 2D histograms, in the neutral
+style or in that of ATLAS, CMS, LHCb, ALICE or DUNE.
 
 ## Installation
 
@@ -88,16 +104,16 @@ files are both supported.
 ```python
 import rootfig as rf
 
-# Overlay two samples, normalised to unity, with a ratio panel.
+# Overlay two samples, each normalised to unity, with a Signal / Background panel.
 rf.plot(
-    ["signal.root", "background.root"],
+    {"Signal": "signal.root", "Background": "background.root"},
     "Muon_pt",
     tree="events",
     selection="abs(Muon_eta) < 2.5",
     weight="event_weight",
     bins=(50, 0, 200),
     normalize=True,
-    ratio=True,
+    ratio="Background",
 )
 ```
 
@@ -140,8 +156,14 @@ matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
   `count(Jet_pt) >= 2` or `Muon_pt > 20`; event and object selections have
   explicit rules, and event weights carry through to each selected object.
 - **Compare samples with a few keywords.** Overlays, stacks, data points and
-  ratio panels share binning and propagate histogram uncertainties.
-  Normalise to unity, density, bin width or luminosity.
+  ratio panels share binning and propagate histogram uncertainties; bin edges
+  and `(n, low, high)` are used as given, while a range inferred from the data
+  ignores far outliers, so `-999` sentinels do not set the axis. Normalise to
+  unity, density, bin width or luminosity.
+- **Show systematic uncertainties.** Attach weight, branch, file or
+  normalisation variations to a sample; stacks and ratio panels draw the
+  combined statistical and systematic band, and every component stays
+  accessible.
 - **Style figures for your analysis.** Add experiment labels, units, log axes
   and broken axes, then refine the result with matplotlib.
 - **Go beyond 1D plots.** Draw 2D histograms, correlations, efficiencies,
@@ -172,7 +194,7 @@ stack, building on familiar libraries:
 | --- | --- | --- |
 | Reading ROOT files | [uproot](https://github.com/scikit-hep/uproot5) | file globs, tree auto-detection, reading only the required branches |
 | Jagged arrays | [Awkward Array](https://github.com/scikit-hep/awkward) | the per-event/per-object rules for cuts and weights |
-| Histograms | [hist](https://github.com/scikit-hep/hist) / boost-histogram | shared binning, automatic ranges, normalisation, ratios |
+| Histograms | [hist](https://github.com/scikit-hep/hist) / boost-histogram | shared binning, robust automatic ranges, normalisation, ratios |
 | Drawing | [mplhep](https://github.com/scikit-hep/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
@@ -192,6 +214,21 @@ uv run mypy
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
+## Citation
+
+If `rootfig` is useful in your research, please cite it:
+
+```bibtex
+@software{rootfig,
+  author = {Beirer, Joshua Falco},
+  doi = {10.5281/zenodo.22726311},
+  license = {MIT},
+  title = {{rootfig}},
+  url = {https://github.com/jbeirer/rootfig},
+  year = {2026}
+}
+```
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{rootfig-0.2.2 → rootfig-0.4.0}/README.md

@@ -1,19 +1,32 @@
-# rootfig
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jbeirer/rootfig/main/.github/assets/rootfig-logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/jbeirer/rootfig/main/.github/assets/rootfig-logo-light.svg">
+    <img src="https://raw.githubusercontent.com/jbeirer/rootfig/main/.github/assets/rootfig-logo-light.svg" alt="rootfig" width="560">
+  </picture>
+</p>
 
-**Publication-quality figures straight from ROOT trees, without ROOT.**
+<p align="center">
+  <strong>Publication-quality figures straight from ROOT trees, without ROOT.</strong>
+</p>
 
-[![Docs](https://img.shields.io/badge/docs-online-blue)](https://jbeirer.github.io/rootfig/)
-[![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)
+<p align="center">
+  <a href="https://jbeirer.github.io/rootfig/">Documentation</a> ·
+  <a href="https://jbeirer.github.io/rootfig/gallery/">Gallery</a> ·
+  <a href="https://jbeirer.github.io/rootfig/quickstart/">Quick start</a>
+</p>
 
-**[Documentation](https://jbeirer.github.io/rootfig/) ·
-[Gallery](https://jbeirer.github.io/rootfig/gallery/) ·
-[Quick start](https://jbeirer.github.io/rootfig/quickstart/)**
+<p align="center">
+  <a href="https://jbeirer.github.io/rootfig/"><img src="https://img.shields.io/badge/docs-online-blue" alt="Documentation"></a>
+  <a href="https://doi.org/10.5281/zenodo.22726311"><img src="https://zenodo.org/badge/1366702602.svg" alt="DOI"></a>
+  <a href="https://github.com/jbeirer/rootfig/actions/workflows/ci.yml"><img src="https://github.com/jbeirer/rootfig/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/jbeirer/rootfig"><img src="https://codecov.io/gh/jbeirer/rootfig/branch/main/graph/badge.svg" alt="codecov"></a>
+  <a href="https://pypi.org/project/rootfig/"><img src="https://img.shields.io/pypi/v/rootfig.svg" alt="PyPI"></a>
+  <a href="https://pypi.org/project/rootfig/"><img src="https://img.shields.io/pypi/pyversions/rootfig.svg" alt="Python"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
 
-Go from ROOT files to a styled figure in one call. Choose a variable, add a
+Go from a ROOT file to a styled figure in one call. Choose a variable, add a
 selection, and plot:
 
 ```python
@@ -24,20 +37,23 @@ rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=
 
 Start with a single distribution; add samples, weights, stacks and ratio
 panels as your analysis grows. Every plot gives you a matplotlib figure to
-customise and save. No ROOT installation required.
+customise and save.
 
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/stack_data.png" alt="Stacked simulation with data and a ratio panel" width="48%"></a>
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/log_axes/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/log_axes-dark.png"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/hist2d/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/hist2d-dark.png"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></picture></a>
 </p>
 <p align="center">
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/object_vs_event.png" alt="Per-object versus per-event selections" width="48%"></a>
-  <a href="https://jbeirer.github.io/rootfig/gallery/"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="48%"></a>
+  <a href="https://jbeirer.github.io/rootfig/gallery/xbreak_ratio/#atlas"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/xbreak_ratio-atlas-dark.png"><img src="docs/images/gallery/xbreak_ratio-atlas.png" alt="Broken x axis with a ratio panel" width="46%"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/luminosity/"><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/gallery/luminosity-dark.png"><img src="docs/images/gallery/luminosity.png" alt="FCC-ee stack scaled to luminosity with a significance panel" width="43%"></picture></a>
 </p>
 
 **[Explore the gallery →](https://jbeirer.github.io/rootfig/gallery/)**
 See each figure alongside the code that makes it, from simple overlays to
-stacked data/MC comparisons, broken axes and 2D histograms.
+stacked data/MC comparisons, broken axes and 2D histograms, in the neutral
+style or in that of ATLAS, CMS, LHCb, ALICE or DUNE.
 
 ## Installation
 
@@ -55,16 +71,16 @@ files are both supported.
 ```python
 import rootfig as rf
 
-# Overlay two samples, normalised to unity, with a ratio panel.
+# Overlay two samples, each normalised to unity, with a Signal / Background panel.
 rf.plot(
-    ["signal.root", "background.root"],
+    {"Signal": "signal.root", "Background": "background.root"},
     "Muon_pt",
     tree="events",
     selection="abs(Muon_eta) < 2.5",
     weight="event_weight",
     bins=(50, 0, 200),
     normalize=True,
-    ratio=True,
+    ratio="Background",
 )
 ```
 
@@ -107,8 +123,14 @@ matplotlib `Figure`/`Axes`, `p.hists` are `hist.Hist` objects, and
   `count(Jet_pt) >= 2` or `Muon_pt > 20`; event and object selections have
   explicit rules, and event weights carry through to each selected object.
 - **Compare samples with a few keywords.** Overlays, stacks, data points and
-  ratio panels share binning and propagate histogram uncertainties.
-  Normalise to unity, density, bin width or luminosity.
+  ratio panels share binning and propagate histogram uncertainties; bin edges
+  and `(n, low, high)` are used as given, while a range inferred from the data
+  ignores far outliers, so `-999` sentinels do not set the axis. Normalise to
+  unity, density, bin width or luminosity.
+- **Show systematic uncertainties.** Attach weight, branch, file or
+  normalisation variations to a sample; stacks and ratio panels draw the
+  combined statistical and systematic band, and every component stays
+  accessible.
 - **Style figures for your analysis.** Add experiment labels, units, log axes
   and broken axes, then refine the result with matplotlib.
 - **Go beyond 1D plots.** Draw 2D histograms, correlations, efficiencies,
@@ -139,7 +161,7 @@ stack, building on familiar libraries:
 | --- | --- | --- |
 | Reading ROOT files | [uproot](https://github.com/scikit-hep/uproot5) | file globs, tree auto-detection, reading only the required branches |
 | Jagged arrays | [Awkward Array](https://github.com/scikit-hep/awkward) | the per-event/per-object rules for cuts and weights |
-| Histograms | [hist](https://github.com/scikit-hep/hist) / boost-histogram | shared binning, automatic ranges, normalisation, ratios |
+| Histograms | [hist](https://github.com/scikit-hep/hist) / boost-histogram | shared binning, robust automatic ranges, normalisation, ratios |
 | Drawing | [mplhep](https://github.com/scikit-hep/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
@@ -159,6 +181,21 @@ uv run mypy
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
+## Citation
+
+If `rootfig` is useful in your research, please cite it:
+
+```bibtex
+@software{rootfig,
+  author = {Beirer, Joshua Falco},
+  doi = {10.5281/zenodo.22726311},
+  license = {MIT},
+  title = {{rootfig}},
+  url = {https://github.com/jbeirer/rootfig},
+  year = {2026}
+}
+```
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{rootfig-0.2.2 → rootfig-0.4.0}/docs/api.md

@@ -18,6 +18,7 @@
 ::: rootfig.ratio
 ::: rootfig.log_bins
 ::: rootfig.use_style
+::: rootfig.dark_theme
 
 ## Descriptions
 
@@ -25,12 +26,14 @@
 ::: rootfig.Variable
 ::: rootfig.Cut
 ::: rootfig.Style
+::: rootfig.Systematic
 
 ## Results
 
 ::: rootfig.Plot
 ::: rootfig.Histogram
 ::: rootfig.Ratio
+::: rootfig.Uncertainty
 ::: rootfig.Summary
 ::: rootfig.SummaryTable
 ::: rootfig.Cutflow

{rootfig-0.2.2 → rootfig-0.4.0}/docs/composable.md

@@ -28,8 +28,9 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   implementing the [`Source`][rootfig.io.Source] protocol.
 - `selection` and `weight` belong to the sample and combine with the ones
   given to `plot()` (`&` and `*` respectively).
-- `is_data=True` draws black points with error bars, keeps the sample out of
-  stacks and makes it the numerator of ratios.
+- `is_data=True` draws points with error bars (in the style's text colour
+  unless `color` is set), keeps the sample out of stacks and makes it the
+  numerator of ratios.
 - `xsec` and `ngen` describe simulated processes: the cross section (pb, or a
   string with a unit such as `"1.2 fb"`) and the number of generated events (a
   number, the name of an object in the file holding it, e.g. FCCAnalyses'
@@ -48,6 +49,13 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   (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].
+- `systematics={name: variation}` lists the sample's sources of systematic
+  uncertainty: weight expressions (`("w_up", "w_down")`), normalisation
+  uncertainties (`0.05`, `(1.1, 0.95)`), varied branches
+  (`{"Jet_pt": ("Jet_pt_up", "Jet_pt_down")}`) and varied files
+  ([`Systematic.samples`][rootfig.Systematic]). Sources with
+  the same name are correlated across samples; see
+  [Systematic uncertainties](plotting.md#systematic-uncertainties).
 - `sample.with_(label="...")` returns a modified copy; replacement values are
   validated like constructor arguments.
 
@@ -61,14 +69,16 @@ What to histogram and how to present it.
 ```python
 pt = rf.Variable("Muon_pt", bins=(50, 0, 200), label=r"$p_T^{\mu}$", unit="GeV")
 met = rf.Variable(
-    "MET / 1000", bins=40, range="robust", label=r"$E_T^{miss}$", unit="TeV", log=True, name="met"
+    "MET / 1000", bins=40, range="auto", label=r"$E_T^{miss}$", unit="TeV", log=True, name="met"
 )
 ```
 
-- `bins`: an `int` (range from the data), `(n, low, high)`, a sequence of
-  edges (e.g. `rf.log_bins(30, 1, 1000)`), or a `hist.axis.Regular`/`Variable`.
-- `range`: `(low, high)`, `"auto"` (finite min/max over all samples) or
-  `"robust"` (ignores far outliers such as `-999` sentinels).
+- `bins`: an `int` (range inferred from the data), `(n, low, high)`, a sequence
+  of edges (e.g. `rf.log_bins(30, 1, 1000)`), or a `hist.axis.Regular`/`Variable`.
+- `range`: `(low, high)`, `"robust"` (the default: ignores far outliers such as
+  `-999` sentinels and cuts a thin tail, both of which then land in the
+  under/overflow) or `"auto"` (the finite min/max over all samples). See
+  [Binning and range](plotting.md#binning-and-range).
 - `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)`; it must be a plain
@@ -111,8 +121,12 @@ neutral = rf.Style(
   given.
 - `base` can be any mplhep or matplotlib style name (`"ATLAS"`, `"ggplot"`,
   ...) or a mapping of rcParams; `rc` adds overrides on top; `colors` replaces
-  the colour cycle. `label_loc` is mplhep's label position (0 above the axes,
-  1 to 4 inside the corners), overriding the experiment's convention.
+  the colour cycle. `label_loc` overrides the experiment's convention: 0 puts
+  the experiment and secondary text above the frame; 3 puts the experiment
+  above and secondary text inside; 1, 2, and 4 put both inside. Luminosity stays
+  above for locations 0–3 and inside for 4. 2D histograms and correlation
+  matrices default to location 0; only `label_loc=1`, `2`, or `4` moves the
+  experiment inside the frame.
 - The centre-of-mass energy and luminosity appear only when `com`/`lumi` are
   given; nothing is invented for you.
 - `legend` is `True`, `False` or a location string; `legend_kwargs` are

rootfig-0.4.0/docs/gallery/index.md

@@ -0,0 +1,67 @@
+---
+hide:
+  - toc
+---
+
+# Gallery
+
+Every figure below is drawn by the code on its page. Most examples use a toy
+ROOT dataset: three simulated processes and one "observed" sample with muons,
+jets and event-level quantities. The in-memory arrays example generates its
+own NumPy data.
+
+Choose a style: examples with style tabs follow your choice here and on their
+individual pages. The other examples keep their own styles.
+
+<!-- gallery-overview -->
+
+## Run the examples
+
+The examples live in
+[`examples/gallery`](https://github.com/jbeirer/rootfig/blob/main/examples/gallery/__init__.py),
+and one command writes the toy files and every figure in a few seconds:
+
+```bash
+python examples/gallery                # everything ends up in examples/out/
+python examples/gallery --style CMS    # CMS for examples with style tabs
+```
+
+Each picture is also the reference image the test suite compares against, so
+what you see is what the current release draws.
+
+## Beyond figures
+
+The same inputs feed tables and arrays (`mc` and `signal` are the samples from
+the setup block of the example pages):
+
+```python
+# 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, raw counts and step efficiencies per sample
+print(
+    rf.cutflow(
+        mc,
+        ["nMuon >= 2", rf.Cut("MET > 50", label="MET > 50 GeV"), "any(Jet_btag > 0.8)"],
+    )
+)
+
+# evaluated expressions as an Awkward record array
+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(signal, "MET", bins=(40, 0, 400), selection="nJet >= 2")
+```
+
+Cuts compose with `&`, `|` and `~`, carry optional labels, and combine with
+selections given to `plot()`:
+
+```python
+base = rf.Cut("nMuon >= 2", label="2 muons")
+signal_region = base & "abs(Muon_eta) < 2.4" & ~rf.Cut("any(Jet_btag > 0.8)")
+control_region = base & rf.Cut("any(Jet_btag > 0.8)") | "MET > 200"
+```
+
+See [Plotting options](../plotting.md) for every keyword and
+[Expressions and selections](../expressions.md) for the per-event/per-object rules.