rootfig 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.4.0
+Version: 0.6.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/
@@ -197,8 +197,9 @@ stack, building on familiar libraries:
 | 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
-the same options. If you want the arrays, `rf.load` returns them. See
+If your histograms already exist, `rf.plot` draws them too: name a `TH1`
+stored in the file instead of a branch (`rf.plot("zh_histo.root", "m_recoil")`),
+or pass `hist.Hist` objects directly. If you want the arrays, `rf.load` returns them. See
 [the ecosystem guide](https://jbeirer.github.io/rootfig/ecosystem/) for details.
 
 ## Development

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

@@ -164,8 +164,9 @@ stack, building on familiar libraries:
 | 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
-the same options. If you want the arrays, `rf.load` returns them. See
+If your histograms already exist, `rf.plot` draws them too: name a `TH1`
+stored in the file instead of a branch (`rf.plot("zh_histo.root", "m_recoil")`),
+or pass `hist.Hist` objects directly. If you want the arrays, `rf.load` returns them. See
 [the ecosystem guide](https://jbeirer.github.io/rootfig/ecosystem/) for details.
 
 ## Development

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

@@ -3,7 +3,6 @@
 ## Top level
 
 ::: rootfig.plot
-::: rootfig.plot_histograms
 ::: rootfig.plot2d
 ::: rootfig.histogram
 ::: rootfig.histograms

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

@@ -45,6 +45,9 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   ```
 
   Without a luminosity such samples raise a [`LuminosityError`][rootfig.LuminosityError].
+  The same samples can point at files of ready-made histograms instead of
+  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
   ready-made `FileSource`, give the range to the source itself; passing it to
@@ -56,7 +59,7 @@ mem = rf.Sample({"x": awkward_array, "w": weights}, label="in memory")
   ([`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
+- `sample.replace(label="...")` returns a copy with the given fields changed; new values are
   validated like constructor arguments.
 
 Passing a list of files to `plot()` creates one sample per file. To merge
@@ -75,6 +78,10 @@ met = rf.Variable(
 
 - `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`.
+  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
+  [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
   under/overflow) or `"auto"` (the finite min/max over all samples). See

{rootfig-0.4.0 → rootfig-0.6.0}/docs/ecosystem.md

@@ -31,7 +31,9 @@ fills `hist.Hist` with `Weight` storage (sum of weights and sum of squared
 weights per bin), including under/overflow bins, and returns them unchanged:
 `rf.histogram` gives you the `hist.Hist`, `Plot.hists` lists them. Rebinning,
 projecting, slicing, saving to ROOT files with uproot: all of that is hist
-functionality and works directly on the returned objects.
+functionality and works directly on the returned objects. Histograms stored
+in ROOT files (`TH1`, `TH2`) are converted by uproot's `to_hist()`; rootfig
+adds the summing over files, the scaling and the drawing.
 
 ## mplhep
 

{rootfig-0.4.0 → rootfig-0.6.0}/docs/plotting.md

@@ -1,8 +1,8 @@
 # Plotting options
 
-All options below are keyword arguments of [`rf.plot`][rootfig.plot] (and of
-[`rf.plot_histograms`][rootfig.plot_histograms], which draws existing
-`hist.Hist` objects with the same options).
+All options below are keyword arguments of [`rf.plot`][rootfig.plot], whether
+it fills from a tree, reads a histogram stored in the file or draws histogram
+objects you already have (see [the end of this page](#histograms-that-already-exist)).
 
 ## Overlays, stacks and data
 
@@ -109,11 +109,12 @@ p.ratios[0].syst_band  # relative (down, up) band of the reference
 
 Pre-filled histograms take variations directly and are drawn the same way:
 `rf.Histogram(h, label="MC", variations={"jes": (h_up, h_down)})` passed to
-`plot_histograms`; [`uncertainty`][rootfig.histograms.uncertainty] and
+`plot`; [`uncertainty`][rootfig.histograms.uncertainty] and
 [`sum_histograms`][rootfig.histograms.sum_histograms] work on them too.
 
 Use `(h_up, None)` for a mirrored variation. `Sample.systematics` and
-`Histogram.variations` are read-only; change them with `with_(...)`.
+`Histogram.variations` are read-only; `sample.replace(systematics=...)` and
+`histogram.replace(variations=...)` return copies with other ones.
 
 ## Luminosity
 
@@ -142,7 +143,7 @@ dataset scaled to the full one, for instance).
 Variances are scaled consistently. Flow bins scale with the same factor; for
 `"width"` and `"density"` they are divided by the width of the neighbouring
 visible bin. Plain `hist.Hist` objects with a count storage passed to
-`plot_histograms` are converted to `Weight` storage first. If such a histogram
+`plot` are converted to `Weight` storage first. If such a histogram
 was filled with weights (or rescaled) its sum of squared weights is lost, and
 rootfig refuses it with a `ValueError` rather than invent uncertainties; pass
 `assume_poisson=True` to use the absolute bin contents as variances (with a
@@ -450,3 +451,117 @@ table = rf.summarize([sig, bkg], ["MET", "Muon_pt"], selection="nMuon > 0", weig
 print(table)  # aligned text table
 table.get("MET", "Signal").mean  # a Summary: entries, mean, std, sem, skewness, min, max
 ```
+
+## Histograms that already exist
+
+`rf.plot`, `rf.histogram(s)` and `rf.plot2d` read histograms stored in ROOT
+files; `rf.plot` and `rf.plot2d` also draw histogram objects you already have.
+Each keeps its usual drawing options where they apply: the 1D options above
+for `rf.plot` (stacks, ratios, `flow`, ...), those of the
+[2D section](#2d-histograms-and-correlations) for `rf.plot2d`. Options that
+need information a ready-made histogram no longer has (a selection, a weight,
+`stats` on one without statistics) are refused.
+
+### Histograms already in ROOT files
+
+Analysis frameworks often write their selections out as `TH1`/`TH2` objects,
+one file per process (FCCAnalyses' `<process>_<selection>_histo.root`, for
+instance). Name the histogram where a branch would go:
+
+```python
+samples = {
+    "ZH": rf.Sample("final/p8_ee_ZH_ecm240_sel1_histo.root", color="C3", scale=10),
+    "VV": ["final/p8_ee_WW_ecm240_sel1_histo.root", "final/p8_ee_ZZ_ecm240_sel1_histo.root"],
+}
+rf.plot(
+    samples,
+    "leptonic_recoil_m",
+    bins=50,
+    stack=True,
+    logy=True,
+    xlabel="Z leptonic recoil",
+    unit="GeV",
+    style=rf.Style(com=240, com_unit="GeV", lumi=5, lumi_unit="ab^{-1}"),
+)
+h = rf.histogram("final/p8_ee_ZH_ecm240_sel0_histo.root", "mz")  # a hist.Hist
+rf.plot2d("final/p8_ee_ZH_ecm240_sel0_histo.root", "mz_recoil_2D")  # a stored TH2
+```
+
+The decision is made per call and is deterministic. A variable that is a bare
+name is read as a stored histogram when every sample reads files without an
+explicit `tree=` or entry range, the first file of each sample holds a `TH1` or
+`TH2` of that name, and the file has no tree or its only tree has no branch of
+that name. Anything else fills from the tree as usual: an explicit
+`tree=` always means a branch, a branch of the same name wins over a histogram,
+a file with several trees next to the histogram raises (pass `tree=` for a
+branch, or read the histogram with `FileSource.read_histogram`), and samples
+that disagree raise with the reason per sample. A histogram inside a directory
+is named by its path in backticks, like a branch with odd characters:
+`` rf.plot("histo.root", "`selection/mz`") ``.
+
+What a stored histogram supports:
+
+- The files of one `Sample` are summed (they must agree on the binning);
+  `scale`, `color`, `is_data`, `histtype` and the luminosity scaling
+  (`Sample(xsec=..., ngen=...)` with `lumi=`, `ngen` may name a `TParameter`
+  or a sum-of-weights histogram in the same file) apply as for trees. A file
+  without a tree has no entries to count, so it needs `ngen`.
+- The stored axis title is the x label unless `xlabel=`/a `Variable` label is
+  given; a `unit=` is appended to it and, as for trees, feeds the bin-width y
+  label (`Events / 5 GeV`). A title that ends in `[unit]` already supplies it.
+  A placeholder title (none, ROOT's `xaxis`, uproot's `Axis 0`) gives way to the
+  variable's name. The y axis of a `TH2` named by a single variable gets no
+  label from that name, which describes the histogram rather than the axis; as
+  for any unlabelled axis, hist shows the axis name (`mz_recoil_2D_y`) instead.
+  To label it, pass a `Variable` for `y` that names the same histogram, since
+  both axes must resolve to one stored object:
+  `` rf.plot2d(f, "my_hist", rf.Variable("my_hist", name="recoil", label="Recoil")) ``.
+  A `Variable` with another expression asks for a branch instead.
+- `bins=` merges the stored bins: an integer count (it must divide the stored
+  count), or edges that coincide with the stored ones (`(n, low, high)`, a
+  sequence of edges, or an `int` with `range=(low, high)`) and merge the bins
+  between them. The `Variable` written for the tree therefore also describes
+  the histogram filled from it, as its own edges or a coarser aligned set. With
+  `bins=None` the stored binning is kept. Other edges cannot be made, and an
+  explicit `(low, high)` range without a bin count cannot be applied: use
+  `xlim=` to zoom. `range="auto"` and `"robust"` have no effect on a histogram
+  that is already filled.
+- Normalisation, stacks, ratios, `flow` and the other drawing options work
+  unchanged. Systematics of the normalisation kind (`{"lumi": 0.02}`) and
+  `Systematic.samples(other_files)` (the same histogram read from other files)
+  are supported by `plot` and `histograms`; `plot2d` ignores systematics, for
+  stored histograms as for trees.
+- `selection=`, `weight=` (on the call or the `Sample`), `nonfinite="error"`,
+  an explicit `(low, high)` range without a bin count, weight and
+  branch-replacement systematics and `stats=` need event data and raise with a
+  message that says so.
+- A `TH1` written with `Sumw2` keeps its uncertainties; one without it arrives
+  with its bin contents as variances (uproot cannot know the weights). Negative
+  contents without `Sumw2` leave no usable variances: rootfig refuses them unless
+  `assume_poisson=True` takes the absolute contents, as for histogram objects.
+  The files of one sample may mix both kinds and may differ in their axis
+  titles; the sum has `Weight` storage and the first file's titles.
+
+### Histogram objects
+
+`hist.Hist` or [`Histogram`][rootfig.Histogram] objects, one or a list, are
+drawn as they are: `rf.plot([h_sig, h_bkg], label=["Signal", "Background"],
+ratio=True)`. `label=` names plain `hist.Hist` objects (otherwise their first
+axis name is used), `observed=` takes histogram objects for the data,
+`variable=` optionally supplies the axis label, unit and `log` flag, and
+`rf.plot2d(h2)` draws a 2D one, with `x` and `y` `Variable`s optionally
+describing its axes the same way (`rf.plot2d(h2, rf.Variable("mass",
+label="Mass", unit="GeV"), rf.Variable("recoil", bins=6))`; a `name=` renames
+the axis, the histogram you passed is left untouched). As for stored histograms, `bins=` (given
+directly or on the `Variable`) merges bins: an integer count, or edges that
+coincide with the existing ones, so the `Variable` a histogram was filled with
+can be passed along with it (`rf.plot(rf.histogram(sample, pt), pt)`), also
+after normalising it, as long as it asks for the bins the histogram has. An
+explicit `(low, high)` range without a bin count and the options that fill
+from event data (`tree`, `selection`, `weight`, `lumi`, `systematics`) raise;
+`range="auto"`/`"robust"` are no-ops. `Histogram.variations` carries
+systematics instead. Stacks, sums and ratios of histograms with category axes
+(ROOT bin labels) require the same categories in the same order; the flow bins
+of such an axis hold entries of categories it does not list, which
+`flow="hint"` marks with an arrow and `flow="show"`/`flow="sum"` refuse, since
+they have no bin beyond the last category.

{rootfig-0.4.0 → rootfig-0.6.0}/examples/gallery/__init__.py

@@ -231,7 +231,7 @@ def stack_data(mc: list[rf.Sample], data: rf.Sample, pt: rf.Variable, style: rf.
     "Systematic uncertainties in a stack and its ratio panel",
     section=SIMULATION_AND_DATA,
 )
-def systematics(mc: list[rf.Sample], data: rf.Sample, met: rf.Variable, style: rf.Style) -> rf.Plot:
+def systematics(signal: rf.Sample, data: rf.Sample, met: rf.Variable, style: rf.Style) -> rf.Plot:
     """A sample lists its sources of systematic uncertainty by name: a pair of weight
     expressions, a relative normalisation uncertainty, or a mapping of shifted branches,
     which also move the selection. ``systematics=`` on the plot adds a
@@ -239,15 +239,24 @@ def systematics(mc: list[rf.Sample], data: rf.Sample, met: rf.Variable, style: r
     statistical and systematic uncertainties; a source with the same name in several
     samples is correlated, different sources add in quadrature. ``p.uncertainty()``
     returns every component."""
-    zjets, diboson, signal = mc
     jes = {"MET": ("MET_jesUp", "MET_jesDown")}
-    varied = [
-        zjets.with_(systematics={"pileup": ("weight_pu_up", "weight_pu_down"), "jes": jes}),
-        diboson.with_(systematics={"jes": jes, "xsec": 0.10}),
-        signal,
-    ]
+    zjets = rf.Sample(
+        "background.root",
+        tree="events",
+        label="Z + jets",
+        weight="weight",
+        systematics={"pileup": ("weight_pu_up", "weight_pu_down"), "jes": jes},
+    )
+    diboson = rf.Sample(
+        "diboson.root",
+        tree="events",
+        label="Diboson",
+        weight="weight",
+        scale=0.15,
+        systematics={"jes": jes, "xsec": 0.10},
+    )
     return rf.plot(
-        varied,
+        [zjets, diboson, signal],
         met,
         observed=data,
         stack=True,
@@ -272,9 +281,9 @@ def ratio_reference(
     stays visible on light and dark pages."""
     return rf.plot(
         [
-            zjets.with_(color=plt.rcParams["text.color"], histtype="errorbar"),
-            diboson.with_(color="#d95f02"),
-            signal.with_(color="#1b9e77", histtype="fill"),
+            zjets.replace(color=plt.rcParams["text.color"], histtype="errorbar"),
+            diboson.replace(color="#d95f02"),
+            signal.replace(color="#1b9e77", histtype="fill"),
         ],
         rf.Variable("nJet", bins=(9, -0.5, 8.5), label="Jet multiplicity"),
         normalize=True,
@@ -413,12 +422,12 @@ def density_flow(
 def object_vs_event(signal: rf.Sample, pt: rf.Variable, style: rf.Style) -> rf.Plot:
     """``Muon_pt`` is a list per event. A per-object cut such as ``Muon_pt > 100`` masks
     individual muons, while ``any(Muon_pt > 100)`` is per event: it keeps whole events, with all
-    their muons, soft ones included. ``Sample.with_`` derives variants of a sample."""
+    their muons, soft ones included. ``Sample.replace`` derives variants of a sample."""
     return rf.plot(
         [
-            signal.with_(label="All muons"),
-            signal.with_(label="Muon_pt > 100", selection="Muon_pt > 100"),
-            signal.with_(label="any(Muon_pt > 100)", selection="any(Muon_pt > 100)"),
+            signal.replace(label="All muons"),
+            signal.replace(label="Muon_pt > 100", selection="Muon_pt > 100"),
+            signal.replace(label="any(Muon_pt > 100)", selection="any(Muon_pt > 100)"),
         ],
         pt,
         logy=True,
@@ -430,15 +439,16 @@ def object_vs_event(signal: rf.Sample, pt: rf.Variable, style: rf.Style) -> rf.P
 def expressions(signal: rf.Sample, pt: rf.Variable, style: rf.Style) -> rf.Plot:
     """Variables are expressions with NumPy functions and per-event reductions:
     ``first(Muon_pt)`` is the leading muon, ``Muon_pt * cosh(Muon_eta)`` the muon momentum.
-    ``rf.histogram`` returns a plain ``hist.Hist``; ``rf.plot_histograms`` draws any collection
-    of them with the usual options."""
+    ``rf.histogram`` returns a plain ``hist.Hist``; ``rf.plot`` draws any collection of
+    histogram objects with the usual options."""
     all_muons = rf.histogram(signal, pt)
-    leading = rf.histogram(signal, pt.with_(expression="first(Muon_pt)"))
-    momentum = rf.histogram(signal, pt.with_(expression="Muon_pt * cosh(Muon_eta)"))
-    return rf.plot_histograms(
+    leading = rf.histogram(signal, pt.replace(expression="first(Muon_pt)"))
+    momentum = rf.histogram(signal, pt.replace(expression="Muon_pt * cosh(Muon_eta)"))
+    return rf.plot(
         [all_muons, leading, momentum],
-        labels=["All muons", "Leading muon", r"Muon $|\vec{p}|$"],
-        variable=pt.with_(label=r"$p_T^{\mu}$ or $|\vec{p}^{\,\mu}|$"),
+        label=["All muons", "Leading muon", r"Muon $|\vec{p}|$"],
+        xlabel=r"$p_T^{\mu}$ or $|\vec{p}^{\,\mu}|$",
+        unit="GeV",
         logy=True,
         style=style,
     )

{rootfig-0.4.0 → rootfig-0.6.0}/src/rootfig/__init__.py

@@ -22,7 +22,6 @@ from rootfig.api import (
     load,
     plot,
     plot2d,
-    plot_histograms,
     profile,
     summarize,
 )
@@ -54,7 +53,7 @@ from rootfig.histograms import (
 from rootfig.model import Cut, Sample, Style, Systematic, Variable, log_bins
 from rootfig.plotting import Plot, dark_theme, use_style
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"
 
 __all__ = [
     "BinningError",
@@ -94,7 +93,6 @@ __all__ = [
     "log_bins",
     "plot",
     "plot2d",
-    "plot_histograms",
     "profile",
     "ratio",
     "significance",

rootfig-0.6.0/src/rootfig/_storage.py

@@ -0,0 +1,166 @@
+"""``Weight``-storage conversion, binning comparison and bin-wise addition of ``hist`` objects.
+
+Shared by :mod:`rootfig.io` (histograms read from files) and
+:mod:`rootfig.histograms`, so both apply one policy for uncertainties and for
+what counts as the same binning.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Iterable
+from typing import Any
+
+import hist
+import numpy as np
+
+from rootfig._typing import Hist
+from rootfig.errors import RootfigWarning
+
+__all__ = ["add_hists", "add_into", "as_weight_storage", "is_category", "same_axis", "same_binning"]
+
+_COUNT_STORAGES = (
+    hist.storage.Double,
+    hist.storage.Int64,
+    hist.storage.AtomicInt64,
+    hist.storage.Unlimited,
+)
+
+
+def as_weight_storage(histogram: Hist, *, assume_poisson: bool = False) -> Hist:
+    """Return ``histogram`` with ``Weight`` storage (a copy if it had another storage).
+
+    Plain count storages (``Double``, ``Int64``, ...) carry no sum of squared
+    weights; their variances are taken as ``hist`` reports them, i.e. the
+    counts (Poisson) for unweighted fills. Two cases leave no usable variances:
+    after a weighted fill or arithmetic on such a storage ``hist`` reports none
+    at all, and a count storage with negative contents reports negative ones
+    (the counts). Either is an error unless ``assume_poisson=True``, which uses
+    the absolute bin contents as variances (the Poisson guess; a
+    :class:`~rootfig.errors.RootfigWarning` says so). A ``Weight`` storage is
+    returned as it is unless it reports negative variances, which get the same
+    treatment.
+
+    Raises
+    ------
+    TypeError
+        If the storage is not a count or ``Weight`` storage (``Mean``, ...).
+    ValueError
+        If the histogram has no usable variances and ``assume_poisson`` is False.
+    """
+    if histogram.storage_type is hist.storage.Weight:
+        weight_variances = np.asarray(histogram.variances(flow=True), dtype=float)
+        if not np.any(weight_variances < 0):
+            return histogram
+        what = "histogram with Weight storage reports negative variances"
+        reported: Any = None
+    else:
+        if histogram.ndim and histogram.storage_type not in _COUNT_STORAGES:
+            msg = (
+                f"histograms with {histogram.storage_type.__name__} storage are not supported; "
+                "use Weight (or a plain count) storage"
+            )
+            raise TypeError(msg)
+        reported = histogram.variances(flow=True)
+        if reported is None:
+            what = (
+                f"histogram with {histogram.storage_type.__name__} storage was filled with "
+                "weights or rescaled, so hist reports no variances (the sum of squared weights "
+                "is lost)"
+            )
+        elif np.any(np.asarray(reported) < 0):
+            what = (
+                f"histogram with {histogram.storage_type.__name__} storage has negative bin "
+                "contents, so the counts it reports as variances are negative (the sum of "
+                "squared weights is unknown)"
+            )
+            reported = None
+    values = np.asarray(histogram.values(flow=True), dtype=float)
+    if reported is None:
+        if not assume_poisson:
+            msg = (
+                f"{what}. Fill it with hist.storage.Weight() to keep the uncertainties, or pass "
+                "assume_poisson=True to use the absolute bin contents as variances"
+            )
+            raise ValueError(msg)
+        warnings.warn(
+            f"{what}; using the absolute bin contents as variances (Poisson guess)",
+            RootfigWarning,
+            stacklevel=3,
+        )
+        variances = np.abs(values)  # never a negative variance for signed contents
+    else:
+        variances = np.asarray(reported, dtype=float)
+    result = hist.Hist(*histogram.axes, storage=hist.storage.Weight())
+    view: Any = result.view(flow=True)
+    view.value = values
+    view.variance = variances
+    return result
+
+
+def same_binning(a: Hist, b: Hist, *, flow: bool = True) -> bool:
+    """Return True if two histograms have the same axes up to their names and labels.
+
+    Axis by axis as :func:`same_axis`; ``flow`` asks for the same flow bins too.
+    """
+    if a.ndim != b.ndim:
+        return False
+    return all(
+        same_axis(axis_a, axis_b, flow=flow) for axis_a, axis_b in zip(a.axes, b.axes, strict=True)
+    )
+
+
+def same_axis(axis_a: Any, axis_b: Any, *, flow: bool = True) -> bool:
+    """Return True if two axes bin the same way, whatever their names and labels.
+
+    Two category axes agree when they list the same categories in the same
+    order; two numeric axes (``Regular``, ``Variable`` and ``Integer``
+    interchangeably) when their edges agree to a millionth of the smallest bin
+    width, so bins shifted by a whole width at large coordinates are rejected.
+    A category and a numeric axis never agree. With ``flow`` the under- and
+    overflow bins must be present or absent alike.
+    """
+    if flow and (axis_a.traits.underflow, axis_a.traits.overflow) != (
+        axis_b.traits.underflow,
+        axis_b.traits.overflow,
+    ):
+        return False
+    if is_category(axis_a) or is_category(axis_b):
+        both = is_category(axis_a) and is_category(axis_b)
+        return both and list(axis_a) == list(axis_b)
+    edges_a, edges_b = np.asarray(axis_a.edges, dtype=float), np.asarray(axis_b.edges, dtype=float)
+    if edges_a.shape != edges_b.shape:
+        return False
+    tolerance = 1e-6 * float(min(np.diff(edges_a).min(), np.diff(edges_b).min()))
+    return bool(np.allclose(edges_a, edges_b, rtol=0.0, atol=tolerance))
+
+
+def is_category(axis: Any) -> bool:
+    """Return True for a category axis (``StrCategory``/``IntCategory``: labelled bins)."""
+    return isinstance(axis, hist.axis.StrCategory | hist.axis.IntCategory)
+
+
+def add_into(total: Hist, other: Hist) -> None:
+    """Add ``other`` into ``total`` in place, bin by bin, flow bins included.
+
+    Both have ``Weight`` storage and the same binning (:func:`same_binning`);
+    ``total`` keeps its axes (names and labels), which is what ``hist``'s own
+    addition refuses when the metadata differ.
+    """
+    view: Any = total.view(flow=True)
+    view.value += other.values(flow=True)
+    view.variance += other.variances(flow=True)
+
+
+def add_hists(hists: Iterable[Hist]) -> Hist:
+    """Return the bin-wise sum of ``Weight``-storage histograms with the same binning.
+
+    The first histogram is copied and the others added into the copy one at a
+    time (see :func:`add_into`), so an iterator of histograms is summed without
+    holding them all.
+    """
+    iterator = iter(hists)
+    total = next(iterator).copy()
+    for other in iterator:
+        add_into(total, other)
+    return total

{rootfig-0.4.0 → rootfig-0.6.0}/src/rootfig/api/__init__.py

@@ -8,7 +8,7 @@ their own.
 
 from rootfig.api.data import histogram, histograms, load
 from rootfig.api.measures import efficiency, profile
-from rootfig.api.plots1d import plot, plot_histograms
+from rootfig.api.plots1d import plot
 from rootfig.api.plots2d import correlation, plot2d
 from rootfig.api.tables import SummaryTable, cutflow, summarize
 
@@ -22,7 +22,6 @@ __all__ = [
     "load",
     "plot",
     "plot2d",
-    "plot_histograms",
     "profile",
     "summarize",
 ]

{rootfig-0.4.0 → rootfig-0.6.0}/src/rootfig/api/_common.py

@@ -40,12 +40,12 @@ def style_for(
     """Resolve ``style`` and add free text lines and the luminosity used for scaling."""
     resolved = as_style(style)
     if lumi is not None and resolved.lumi is None:
-        resolved = resolved.with_(lumi=lumi)
+        resolved = resolved.replace(lumi=lumi)
     if text is None:
         return resolved
     existing = list(resolved.text_lines)
     extra = [text] if isinstance(text, str) else list(text)
-    return resolved.with_(text=[*existing, *extra])
+    return resolved.replace(text=[*existing, *extra])
 
 
 def normalize_for_plot(histogram_: Histogram, spec: NormalizeSpec) -> Histogram: