rootfig 0.7.1__tar.gz → 0.9.0__tar.gz

{rootfig-0.7.1 → rootfig-0.9.0}/CONTRIBUTING.md

@@ -50,7 +50,7 @@ src/rootfig/
   io/             file and in-memory data sources
   model/          Sample, Group, Variable, Cut, Style, binning
   selection/      per-event / per-object semantics -> flat columns
-  histograms/     filling, normalisation, ratios, statistics, groups, 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
@@ -62,12 +62,12 @@ 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:
+Almost all tests generate their ROOT files with uproot on the fly. Two files
+that uproot cannot write are committed, produced with ROOT 6.40; rerun their
+scripts only if the layout has to change, and keep the files small.
+
+`tests/data/split_collection.root` has a split `std::vector<struct>` branch and
+a `TParameter` the way podio/EDM4hep and FCCAnalyses write them (PyROOT):
 
 ```python
 import ROOT
@@ -95,6 +95,31 @@ f.Write()
 f.Close()
 ```
 
+`tests/data/embedded_basket.root` holds a tree whose baskets are embedded in its
+branches, without keys of their own, as a tree filled in memory and written
+afterwards keeps them (`root -l -b -q embedded.C`):
+
+```cpp
+// embedded.C
+void embedded() {
+   TTree t("events", "events");
+   t.SetDirectory(nullptr);  // in memory: nothing is flushed while filling
+   Float_t x;
+   std::vector<double> y;
+   t.Branch("x", &x);
+   t.Branch("y", &y);
+   TRandom3 r(1);
+   for (int i = 0; i < 500; ++i) {
+      x = r.Gaus(0, 1);
+      y.assign(i % 4, r.Uniform());
+      t.Fill();
+   }
+   TFile f("embedded_basket.root", "RECREATE");
+   f.WriteObject(&t, "events");
+   f.Close();
+}
+```
+
 ## Figures and the gallery
 
 The `examples/gallery` package is both the showcase and the image-regression

{rootfig-0.7.1 → rootfig-0.9.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.7.1
-Summary: Publication-quality figures straight from ROOT trees, without ROOT: uproot + Awkward + hist + mplhep with a TTree::Draw-like API.
+Version: 0.9.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
@@ -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">
@@ -98,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
 
@@ -114,7 +114,8 @@ rf.plot(
     weight="event_weight",
     bins=(50, 0, 200),
     normalize=True,
-    ratio="Background",
+    panel="ratio",
+    reference="Background",
 )
 ```
 
@@ -139,7 +140,7 @@ p = rf.plot(
     observed=data,
     selection=baseline,
     stack=True,
-    ratio=True,
+    panel="ratio",
     logy=True,
     style=style,
 )
@@ -151,43 +152,24 @@ 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.
 
-Samples that belong to one physics category are drawn as one histogram with
-`rf.Group`. Each keeps its own files, weights, cross section and systematics;
-they are summed only after filling:
+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
-ww = rf.Sample("ww.root", tree="events", label="WW", weight="mc_weight")
-zz = rf.Sample("zz.root", tree="events", label="ZZ", weight="mc_weight")
-vv = rf.Group([ww, zz], label="VV")
+# 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")
 
-rf.plot([vv, signal], pt, observed=data, stack=True, ratio=True, style=style)
-```
-
-Whole sets of plots, every variable under each selection in every drawing
-variant, are one `rf.PlotBook`: it runs that same `rf.plot` call per
-combination and writes deterministically named files:
-
-```python
-book = rf.PlotBook(
-    [vv, signal],
-    [pt, rf.Variable("MET", bins=(40, 0, 200), unit="GeV")],
-    selections={"baseline": baseline, "sr": baseline & "MET > 50"},
-    variants={"lin": {}, "log": {"logy": True}},
-    plot_kwargs={"observed": data, "stack": True, "ratio": True, "style": style},
-)
-book.save("plots/", formats=["pdf", "png"])  # plots/Muon_pt__sr__log.pdf, ...
-book.save_pdf("overview.pdf")  # one automatically arranged multipage PDF
-```
-
-`rf.ALL` discovers the variables instead, from the branch types and stored
-histograms of the files (metadata only), filtered by name:
-
-```python
 book = rf.PlotBook(
-    [vv, signal],
-    variables=rf.ALL,
-    exclude=["*_cov", "*Index"],
+    [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
@@ -195,15 +177,17 @@ book = rf.PlotBook(
 - **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. Draw several samples as one
-  histogram with `rf.Group`, each keeping its own weights, cross section and
-  systematics.
+  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

{rootfig-0.7.1 → rootfig-0.9.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">
@@ -65,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
 
@@ -81,7 +81,8 @@ rf.plot(
     weight="event_weight",
     bins=(50, 0, 200),
     normalize=True,
-    ratio="Background",
+    panel="ratio",
+    reference="Background",
 )
 ```
 
@@ -106,7 +107,7 @@ p = rf.plot(
     observed=data,
     selection=baseline,
     stack=True,
-    ratio=True,
+    panel="ratio",
     logy=True,
     style=style,
 )
@@ -118,43 +119,24 @@ 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.
 
-Samples that belong to one physics category are drawn as one histogram with
-`rf.Group`. Each keeps its own files, weights, cross section and systematics;
-they are summed only after filling:
+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
-ww = rf.Sample("ww.root", tree="events", label="WW", weight="mc_weight")
-zz = rf.Sample("zz.root", tree="events", label="ZZ", weight="mc_weight")
-vv = rf.Group([ww, zz], label="VV")
+# 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")
 
-rf.plot([vv, signal], pt, observed=data, stack=True, ratio=True, style=style)
-```
-
-Whole sets of plots, every variable under each selection in every drawing
-variant, are one `rf.PlotBook`: it runs that same `rf.plot` call per
-combination and writes deterministically named files:
-
-```python
-book = rf.PlotBook(
-    [vv, signal],
-    [pt, rf.Variable("MET", bins=(40, 0, 200), unit="GeV")],
-    selections={"baseline": baseline, "sr": baseline & "MET > 50"},
-    variants={"lin": {}, "log": {"logy": True}},
-    plot_kwargs={"observed": data, "stack": True, "ratio": True, "style": style},
-)
-book.save("plots/", formats=["pdf", "png"])  # plots/Muon_pt__sr__log.pdf, ...
-book.save_pdf("overview.pdf")  # one automatically arranged multipage PDF
-```
-
-`rf.ALL` discovers the variables instead, from the branch types and stored
-histograms of the files (metadata only), filtered by name:
-
-```python
 book = rf.PlotBook(
-    [vv, signal],
-    variables=rf.ALL,
-    exclude=["*_cov", "*Index"],
+    [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
@@ -162,15 +144,17 @@ book = rf.PlotBook(
 - **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. Draw several samples as one
-  histogram with `rf.Group`, each keeping its own weights, cross section and
-  systematics.
+  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

rootfig-0.9.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

{rootfig-0.7.1 → rootfig-0.9.0}/docs/batch.md

@@ -72,8 +72,12 @@ book = rf.PlotBook(
 ```
 
 draws `lin` with `stack=True, logy=False` and `log` with `stack=True, logy=True`.
+With `variants={"stacked": {"stack": True}, "overlaid": {"stack": ["Background"]}}`,
+every plot is drawn with the signal inside the stack and over it, from one set of
+prepared histograms. With the signal last and `panel="s/sqrt(b)"` in
+`plot_kwargs`, both show the same significance panel.
 
-Every other keyword of `rf.plot` (`observed=`, `normalize=`, `ratio=`,
+Every other keyword of `rf.plot` (`observed=`, `normalize=`, `panel=`,
 `systematics=`, `style=`, ...) goes into `plot_kwargs` or a variant. The keyword
 names are checked against `rf.plot`'s signature when the book is built, so a
 misspelt `log_y` is reported, with `logy` as the suggestion, before anything is
@@ -133,7 +137,7 @@ reports it whatever the variable. A branch that a branch-replacement systematic
 replaces is kept only when its replacement is a plottable branch of the sample,
 since the replacement is read whenever the branch is. Stored histograms
 are left out whenever the book is bound to refuse them: a selection, a
-`weight`, `nonfinite="error"`, a `stats` box, a `range` without `bins`, or a
+`weight`, `nonfinite="error"`, a `stats` box, or a
 systematic varying the weight or branches that applies to a sample (the plot's
 unless the sample's own source of that name replaces it, none for observed
 data), in the book's keywords or in any variant's. A file of stored histograms
@@ -257,7 +261,7 @@ a standalone figure.
 
 By default the grid of a page follows the plots it holds. Plots without a lower
 panel or broken axis go up to `2 × 3` on a page; when one of the plots that
-would land on a page has a `ratio=` panel or an `xbreak=`, which need the room,
+would land on a page has a `panel=` or an `xbreak=`, which need the room,
 the page stops at `2 × 2`. The last page adapts to what is left rather than
 leaving a lone plot in the corner of a full grid: seven plain plots are a
 `2 × 3` page followed by a `1 × 1` one, eight a `2 × 3` page and a `1 × 2` one.
@@ -271,9 +275,9 @@ book.save_pdf("overview.pdf", layout=(2, 3))
 A page is as large as the grid of figures the plots would have on their own,
 plus a narrow gap between neighbouring cells, so a plot in a cell keeps its
 usual size: every cell of the document is as large as the largest figure any
-plot of the book would draw alone (a ratio panel makes it taller, a `Style` with
+plot of the book would draw alone (a lower panel makes it taller, a `Style` with
 a `figsize` sets its own). A cell is laid out exactly as a figure of its size,
-whatever the grid and the style: the gap above a ratio panel, the room for
+whatever the grid and the style: the gap above a lower panel, the room for
 labels, the legend and the y limits are the same on a `1 × 1` page as on an
 `8 × 8` one. The plots of a page are finished together, so a dense page takes
 about as long as the same plots on pages of their own. `figsize=` on
@@ -363,7 +367,7 @@ The book only reads less often than that call would. It runs the tasks in
 batches of a few dozen variables: the branches those variables and every
 selection need are read once per sample for the batch, the files a
 `Systematic.samples` variation fills from included, and variants that only
-change the drawing (`logy`, `normalize`, `ratio`, `style`, ...) are drawn from
+change the drawing (`stack`, `logy`, `normalize`, `panel`, `style`, ...) are drawn from
 one set of prepared histograms, each figure from its own copy. A variant that
 changes how the histograms are prepared (`bins`, `weight`, `observed`,
 `systematics`, ...) is prepared on its own, still from the batch's read.
@@ -406,6 +410,63 @@ quietly producing an empty book.
 An axis the book was built without has the single choice `"all"` (selections)
 or `"default"` (variants); selecting it is a no-op and the axis stays implicit.
 
+## A complete example: histogram files
+
+An analysis can write one histogram file per process. Files that already
+contain expected yields are read as they are.
+A `Group` combines the WW and ZZ processes into the VV background category.
+
+```python
+import rootfig as rf
+
+# 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")
+samples = [rf.Group([ww, zz], label="VV"), zh]
+
+fcc = rf.Style(experiment="FCC-ee", status="Simulation", com="240 GeV", lumi="5 ab^-1")
+variants = {
+    "stack": {"stack": True},  # ZH on top of VV
+    "nostack": {"stack": ["VV"]},  # VV stacked, ZH drawn over it
+    "log": {"stack": ["VV"], "logy": True},
+}
+
+# every histogram the files share, at a glance
+rf.PlotBook(samples, rf.ALL, variants=variants, plot_kwargs={"style": fcc}).save_pdf("overview.pdf")
+
+# selected plots, with bins and a range for each histogram
+variables = [
+    rf.Variable("zmumu_recoil_m", bins=(200, 120, 140), label="Recoil mass", unit="GeV"),
+    rf.Variable("zmumu_m", bins=(50, 86, 96), label=r"$m_{\mu\mu}$", unit="GeV"),
+    rf.Variable("zmumu_p", bins=(400, 0, 80), label=r"$p_{\mu\mu}$", unit="GeV"),
+]
+rf.PlotBook(samples, variables, variants=variants, plot_kwargs={"style": fcc}).save_pdf("zh.pdf")
+```
+
+The files are read once per batch of variables. The three variants of each
+variable are drawn from one preparation, so changing the drawing does not
+repeat the reads or the binning.
+
+The stored 1 MeV recoil bins become 0.1 GeV bins between 120 and 140 GeV.
+Everything outside that interval moves into the underflow or overflow bin,
+including its uncertainty. `rf.ALL` keeps each histogram's own binning, which
+suits an overview; explicit `Variable`s choose the ranges and bins to show.
+
+The same plot can be made from ntuples storing the recoil mass as a branch. Give
+the samples cross sections and generated-event counts to scale that plot to
+the same luminosity:
+
+```python
+ww = rf.Sample("ntuples/p8_ee_WW_ecm240/*.root", label="WW", xsec="16.4 pb", ngen="eventsProcessed")
+zz = rf.Sample("ntuples/p8_ee_ZZ_ecm240/*.root", label="ZZ", xsec="1.36 pb", ngen="eventsProcessed")
+zh = rf.Sample(
+    "ntuples/p8_ee_ZH_ecm240/*.root", label="ZH", xsec="0.202 pb", ngen="eventsProcessed"
+)
+recoil = rf.Variable("zed_leptonic_recoil_m", bins=(200, 120, 140), label="Recoil mass", unit="GeV")
+rf.plot([rf.Group([ww, zz], label="VV"), zh], recoil, lumi="5 ab^-1", stack=["VV"], style=fcc)
+```
+
 ## What a book does not do
 
 A book runs its tasks one after another in the calling process and keeps the

{rootfig-0.7.1 → rootfig-0.9.0}/docs/composable.md

@@ -29,11 +29,14 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
 - `selection` and `weight` belong to the sample and combine with the ones
   given to `plot()` (`&` and `*` respectively).
 - `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.
+  unless `color` is set) and keeps the sample out of stacks. In a ratio,
+  relative difference, difference or pull panel it is compared with the
+  prediction by default; `reference=` can name it as the reference instead,
+  and a significance never takes data as a signal (see
+  [the roles](plotting.md#lower-panel)).
 - `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'
+  number, the name of an object in the file holding it, e.g.
   `"eventsProcessed"` `TParameter` or a sum-of-weights histogram, or `None`
   for the number of entries). With `lumi=` given to `plot()`, `cutflow()`,
   `summarize()`, ... every weight is multiplied by `xsec × lumi / ngen`:
@@ -49,7 +52,7 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   trees; naming the histogram in place of the branch reads it (see
   [stored histograms](plotting.md#histograms-already-in-root-files)).
 - `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
+  (a plot reads every file of the sample, a chunk of entries at a time). 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
@@ -121,7 +124,8 @@ met = rf.Variable(
   of edges (e.g. `rf.log_bins(30, 1, 1000)`), or a `hist.axis.Regular`/`Variable`.
   Applied to a histogram that already exists (stored in a file, or filled
   earlier and passed back with the variable), an `int` merges its bins down to
-  that count and explicit edges must coincide with its own; see
+  that count and explicit edges must coincide with its own. The histogram is
+  merged and cropped to the requested edges, with the rest in flow bins; see
   [Histograms that already exist](plotting.md#histograms-that-already-exist).
 - `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
@@ -194,7 +198,7 @@ samples = [bkg, sig]
 variables = [pt, met, rf.Variable("nMuon", bins=(8, -0.5, 7.5))]
 
 for var in variables:
-    p = rf.plot(samples, var, observed=data, selection=sr, stack=True, ratio=True, style=atlas)
+    p = rf.plot(samples, var, observed=data, selection=sr, stack=True, panel="ratio", style=atlas)
     p.save("plots/")  # plots/Muon_pt.pdf, plots/met.pdf, plots/nMuon.pdf
     p.close()
 ```
@@ -208,6 +212,6 @@ rf.PlotBook(
     variables,
     selections={"baseline": base, "sr": sr},
     variants={"lin": {}, "log": {"logy": True}},
-    plot_kwargs={"observed": data, "stack": True, "ratio": True, "style": atlas},
+    plot_kwargs={"observed": data, "stack": True, "panel": "ratio", "style": atlas},
 ).save("plots/")  # plots/Muon_pt__sr__log.pdf, ...
 ```

{rootfig-0.7.1 → rootfig-0.9.0}/docs/ecosystem.md

@@ -41,8 +41,8 @@ adds the summing over files, the scaling and the drawing.
 ships the style sheets and label helpers of the LHC experiments. rootfig
 draws every histogram through `mplhep.histplot`/`hist2dplot` and uses
 mplhep's per-experiment label functions when a `Style(experiment=...)` is
-given. The experiment-neutral default style and the ratio panel are
-rootfig's.
+given. The experiment-neutral default style and the lower panel (ratios,
+differences, pulls, significances) are rootfig's.
 
 ## matplotlib
 
@@ -51,14 +51,30 @@ applies its style only inside a `plt.style.context` while drawing, so it does
 not change global rcParams (unless you call `rf.use_style`). Anything you
 would do to a matplotlib figure, you can do to `Plot.fig` and `Plot.ax`.
 
+## Trees and histogram files
+
+rootfig reads trees and stored `TH1`/`TH2` histograms without ROOT, independently
+of the framework that wrote them. A `Sample` identifies each input process,
+a `Group` combines processes into a category, and `stack=` selects the categories
+to stack. Files already scaled to expected yields are read as they are; trees
+can be scaled with `Sample(xsec=..., ngen=...)` and `lumi=`.
+
+The same `Variable` describes a stored histogram and the branch it was filled
+from: its bins and range crop and merge existing bins, moving the rest into
+flow bins. `PlotBook` prepares each variable once for its drawing variants and
+can discover shared histograms with `rf.ALL`. See the
+[complete histogram-file example](batch.md#a-complete-example-histogram-files).
+
 ## When to use something else
 
-- You already have flat NumPy columns or `boost-histogram` objects and want
-  rich comparison panels: [plothist](https://plothist.readthedocs.io).
+- You have flat NumPy columns rather than ROOT files or histograms, or want a
+  comparison rootfig's lower panel does not offer (an asymmetry, efficiency or
+  goodness-of-fit panel): [plothist](https://plothist.readthedocs.io).
 - You need a full columnar analysis framework with lazy, distributed
   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.
+  the branches a plot needs a chunk of entries at a time, in threads, and holds
+  the values it fills (see [large inputs](plotting.md#large-inputs)), all in one
+  process: it suits quick looks and ntuples that one machine reads in minutes,
+  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.7.1 → rootfig-0.9.0}/docs/expressions.md

@@ -120,7 +120,10 @@ weights (`hist` `Weight` storage).
 ## Missing and non-finite values
 
 `None` values (e.g. `max(Muon_pt)` of an event with no muons) never enter a
-histogram; in a selection they count as `False`. `nan` and `inf` values are
+histogram; in a selection they count as `False`. A whole collection that is
+`None` for an event, whether the variable's, the weight's or the one a
+per-object selection is evaluated on, drops that event, and its objects are
+counted as missing. `nan` and `inf` values are
 dropped with a [`RootfigWarning`][rootfig.RootfigWarning] telling you how
 many, or raise with `nonfinite="error"`. Both counts are recorded in the
 histogram's `stats`.