rootfig 0.6.0__tar.gz → 0.8.0__tar.gz

{rootfig-0.6.0 → rootfig-0.8.0}/CONTRIBUTING.md

@@ -32,6 +32,14 @@ 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.
 
+`key4hep.yml` runs the tests on the Key4hep nightlies (LCG `devkey-head`) and the
+latest Key4hep release, weekly as well, since the stacks change without a commit
+here. `.github/scripts/key4hep-test.sh` installs rootfig into a
+[cvmfs-venv](https://github.com/jbeirer/cvmfs-venv) with `--no-index`, so every
+runtime dependency must come from the stack: the floors in `pyproject.toml` stay
+at or below what the nightlies ship. Locally: `.github/scripts/key4hep-test.sh
+/cvmfs/sw-nightlies.hsf.org/key4hep/setup.sh`.
+
 ## Layout
 
 ```
@@ -40,9 +48,9 @@ src/rootfig/
   errors.py       exception hierarchy
   expressions/    parse, validate and evaluate expression strings
   io/             file and in-memory data sources
-  model/          Sample, Variable, Cut, Style, binning
+  model/          Sample, Group, Variable, Cut, Style, binning
   selection/      per-event / per-object semantics -> flat columns
-  histograms/     filling, normalisation, ratios, statistics, pipeline
+  histograms/     filling, normalisation, comparisons, statistics, groups, pipeline
   plotting/       matplotlib/mplhep rendering, styles, annotations
 tests/            one module per layer plus end-to-end API tests
 docs/             MkDocs sources

{rootfig-0.6.0 → rootfig-0.8.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.6.0
-Summary: Publication-quality figures straight from ROOT trees, without ROOT: uproot + Awkward + hist + mplhep with a TTree::Draw-like API.
+Version: 0.8.0
+Summary: Publication-quality figures straight from ROOT trees and histograms, 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/
 Project-URL: Repository, https://github.com/jbeirer/rootfig
@@ -24,11 +24,11 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: awkward>=2.8
-Requires-Dist: hist>=2.7.2
+Requires-Dist: hist>=2.9
 Requires-Dist: matplotlib>=3.11
-Requires-Dist: mplhep>=1.3
+Requires-Dist: mplhep>=1.2.1
 Requires-Dist: numpy>=1.26
-Requires-Dist: uproot>=5.7.4
+Requires-Dist: uproot>=5.7.1
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <strong>Publication-quality figures straight from ROOT trees, without ROOT.</strong>
+  <strong>Publication-quality figures straight from ROOT trees and histograms, without ROOT.</strong>
 </p>
 
 <p align="center">
@@ -53,6 +53,7 @@ Description-Content-Type: text/markdown
   <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://github.com/jbeirer/rootfig/actions/workflows/key4hep.yml"><img src="https://github.com/jbeirer/rootfig/actions/workflows/key4hep.yml/badge.svg" alt="Key4hep"></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>
@@ -97,7 +98,7 @@ uv add rootfig
 ```
 
 Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
-files are both supported.
+files and stored `TH1`/`TH2` histograms are all supported.
 
 ## Compare samples in one call
 
@@ -113,7 +114,8 @@ rf.plot(
     weight="event_weight",
     bins=(50, 0, 200),
     normalize=True,
-    ratio="Background",
+    panel="ratio",
+    reference="Background",
 )
 ```
 
@@ -138,7 +140,7 @@ p = rf.plot(
     observed=data,
     selection=baseline,
     stack=True,
-    ratio=True,
+    panel="ratio",
     logy=True,
     style=style,
 )
@@ -150,22 +152,51 @@ 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.
 
+For histogram files, `Group` sums processes and a `Variable` crops and merges
+their bins just as it bins a tree. `PlotBook` draws the variants from one
+preparation; `rf.ALL` discovers every shared histogram for an overview.
+
+```python
+# Histogram files: one per process, already scaled to 5 ab^-1
+ww = rf.Sample("outputs/p8_ee_WW_ecm240.root", label="WW")
+zz = rf.Sample("outputs/p8_ee_ZZ_ecm240.root", label="ZZ")
+zh = rf.Sample("outputs/p8_ee_ZH_ecm240.root", label="ZH")
+fcc = rf.Style(experiment="FCC-ee", status="Simulation", com="240 GeV", lumi="5 ab^-1")
+
+book = rf.PlotBook(
+    [rf.Group([ww, zz], label="VV"), zh],
+    [rf.Variable("zmumu_recoil_m", bins=(200, 120, 140), label="Recoil mass", unit="GeV")],
+    variants={"stack": {"stack": True}, "nostack": {"stack": ["VV"]}},
+    plot_kwargs={"style": fcc},
+)
+book.save_pdf("zh.pdf")  # rf.ALL in place of the list plots every histogram the files share
+```
+
 ## What you can do
 
 - **Select events and objects with readable expressions.** Write cuts such as
   `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; bin edges
+- **Compare samples with a few keywords.** Overlays, stacks, data points and a
+  lower panel (ratio, difference, relative difference, pull or significance,
+  against a reference you name) 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.
+  unity, density, bin width or luminosity; stack some samples and overlay the rest.
+  Draw several samples as one histogram with `rf.Group`, each keeping its own
+  weights, cross section and systematics.
 - **Show systematic uncertainties.** Attach weight, branch, file or
-  normalisation variations to a sample; stacks and ratio panels draw the
+  normalisation variations to a sample; stacks and lower 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.
+- **Produce whole sets of plots.** `rf.PlotBook` runs one `rf.plot` call over
+  variables × selections × variants, lazily, and saves each under a
+  deterministic name or all of them as one multipage PDF; `rf.ALL` discovers
+  the variables from the files, and `select()` filters the book down while
+  iterating on a plot.
 - **Go beyond 1D plots.** Draw 2D histograms, correlations, efficiencies,
   profiles, resolutions and significance panels; produce cut flows and
   summary statistics from the same inputs.

{rootfig-0.6.0 → rootfig-0.8.0}/README.md

@@ -7,7 +7,7 @@
 </p>
 
 <p align="center">
-  <strong>Publication-quality figures straight from ROOT trees, without ROOT.</strong>
+  <strong>Publication-quality figures straight from ROOT trees and histograms, without ROOT.</strong>
 </p>
 
 <p align="center">
@@ -20,6 +20,7 @@
   <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://github.com/jbeirer/rootfig/actions/workflows/key4hep.yml"><img src="https://github.com/jbeirer/rootfig/actions/workflows/key4hep.yml/badge.svg" alt="Key4hep"></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>
@@ -64,7 +65,7 @@ uv add rootfig
 ```
 
 Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
-files are both supported.
+files and stored `TH1`/`TH2` histograms are all supported.
 
 ## Compare samples in one call
 
@@ -80,7 +81,8 @@ rf.plot(
     weight="event_weight",
     bins=(50, 0, 200),
     normalize=True,
-    ratio="Background",
+    panel="ratio",
+    reference="Background",
 )
 ```
 
@@ -105,7 +107,7 @@ p = rf.plot(
     observed=data,
     selection=baseline,
     stack=True,
-    ratio=True,
+    panel="ratio",
     logy=True,
     style=style,
 )
@@ -117,22 +119,51 @@ 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.
 
+For histogram files, `Group` sums processes and a `Variable` crops and merges
+their bins just as it bins a tree. `PlotBook` draws the variants from one
+preparation; `rf.ALL` discovers every shared histogram for an overview.
+
+```python
+# Histogram files: one per process, already scaled to 5 ab^-1
+ww = rf.Sample("outputs/p8_ee_WW_ecm240.root", label="WW")
+zz = rf.Sample("outputs/p8_ee_ZZ_ecm240.root", label="ZZ")
+zh = rf.Sample("outputs/p8_ee_ZH_ecm240.root", label="ZH")
+fcc = rf.Style(experiment="FCC-ee", status="Simulation", com="240 GeV", lumi="5 ab^-1")
+
+book = rf.PlotBook(
+    [rf.Group([ww, zz], label="VV"), zh],
+    [rf.Variable("zmumu_recoil_m", bins=(200, 120, 140), label="Recoil mass", unit="GeV")],
+    variants={"stack": {"stack": True}, "nostack": {"stack": ["VV"]}},
+    plot_kwargs={"style": fcc},
+)
+book.save_pdf("zh.pdf")  # rf.ALL in place of the list plots every histogram the files share
+```
+
 ## What you can do
 
 - **Select events and objects with readable expressions.** Write cuts such as
   `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; bin edges
+- **Compare samples with a few keywords.** Overlays, stacks, data points and a
+  lower panel (ratio, difference, relative difference, pull or significance,
+  against a reference you name) 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.
+  unity, density, bin width or luminosity; stack some samples and overlay the rest.
+  Draw several samples as one histogram with `rf.Group`, each keeping its own
+  weights, cross section and systematics.
 - **Show systematic uncertainties.** Attach weight, branch, file or
-  normalisation variations to a sample; stacks and ratio panels draw the
+  normalisation variations to a sample; stacks and lower 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.
+- **Produce whole sets of plots.** `rf.PlotBook` runs one `rf.plot` call over
+  variables × selections × variants, lazily, and saves each under a
+  deterministic name or all of them as one multipage PDF; `rf.ALL` discovers
+  the variables from the files, and `select()` filters the book down while
+  iterating on a plot.
 - **Go beyond 1D plots.** Draw 2D histograms, correlations, efficiencies,
   profiles, resolutions and significance panels; produce cut flows and
   summary statistics from the same inputs.

rootfig-0.8.0/docs/api.md

@@ -0,0 +1,121 @@
+# API reference
+
+## Top level
+
+::: rootfig.plot
+::: rootfig.plot2d
+::: rootfig.histogram
+::: rootfig.api.data.histograms
+    options:
+      heading: rootfig.histograms
+::: rootfig.load
+::: rootfig.summarize
+::: rootfig.correlation
+::: rootfig.cutflow
+::: rootfig.efficiency
+::: rootfig.profile
+::: rootfig.evaluate
+::: rootfig.compare
+::: rootfig.log_bins
+::: rootfig.use_style
+::: rootfig.dark_theme
+
+## Descriptions
+
+::: rootfig.Sample
+::: rootfig.Group
+::: rootfig.Variable
+::: rootfig.Cut
+::: rootfig.Style
+::: rootfig.Systematic
+
+## Batch plotting
+
+::: rootfig.PlotBook
+::: rootfig.PlotTask
+::: rootfig.ALL
+::: rootfig.discover_variables
+::: rootfig.model.check_file_stem
+::: rootfig.model.safe_file_stem
+
+## Results
+
+::: rootfig.Plot
+::: rootfig.Histogram
+::: rootfig.Comparison
+::: rootfig.Uncertainty
+::: rootfig.Summary
+::: rootfig.SummaryTable
+::: rootfig.Cutflow
+::: rootfig.CutflowTable
+::: rootfig.Efficiency
+::: rootfig.Profile
+
+## Errors and warnings
+
+::: rootfig.errors
+
+## Lower layers
+
+These are the layers `rf.plot` is built from, usable on their own; names a module
+does not list here are internal. The descriptions in `rootfig.model` are documented
+above.
+
+::: rootfig.io
+    options:
+      members:
+        - FileSource
+        - ArraySource
+        - Source
+        - ReadCache
+        - as_source
+
+::: rootfig.expressions
+    options:
+      members:
+        - Expression
+        - parse
+        - FUNCTIONS
+        - CONSTANTS
+
+::: rootfig.selection
+    options:
+      members:
+        - prepare
+        - Columns
+        - depth_of
+
+::: rootfig.histograms
+    options:
+      members:
+        - build_histograms
+        - fill
+        - sum_histograms
+        - uncertainty
+        - summarize
+        - read_stored
+        - compatible_binning
+
+<!-- The function shares its name with a submodule; its defining path is unambiguous. -->
+::: rootfig.histograms.normalize.normalize
+    options:
+      heading: normalize
+      heading_level: 3
+
+::: rootfig.plotting
+    options:
+      members:
+        - draw_histograms
+        - draw_panel
+        - draw_hist2d
+        - draw_correlation
+        - draw_efficiencies
+        - draw_profiles
+        - split_stack
+        - make_figure
+        - Layout
+        - figure_size
+        - add_legend
+        - add_stats_box
+        - add_text
+        - style_context