rootfig 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rootfig
-Version: 0.2.2
+Version: 0.3.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,15 +70,17 @@ 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/#logarithmic-axes-with-log-spaced-bins"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/#a-broken-x-axis-peak-and-far-tail-without-the-empty-middle"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="46%"></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/#a-correlation-matrix"><img src="docs/images/gallery/correlation.png" alt="A correlation matrix" width="46%"></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/#a-two-dimensional-histogram"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></a>
 </p>
 
 **[Explore the gallery →](https://jbeirer.github.io/rootfig/gallery/)**
@@ -88,16 +103,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 +155,10 @@ 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.
 - **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 +189,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

{rootfig-0.2.2 → rootfig-0.3.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,15 +37,17 @@ 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/#logarithmic-axes-with-log-spaced-bins"><img src="docs/images/gallery/log_axes.png" alt="Logarithmic axes with log-spaced bins" width="46%"></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/#a-broken-x-axis-peak-and-far-tail-without-the-empty-middle"><img src="docs/images/gallery/xbreak_ratio.png" alt="Broken x axis with a ratio panel" width="46%"></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/#a-correlation-matrix"><img src="docs/images/gallery/correlation.png" alt="A correlation matrix" width="46%"></a>
+  &nbsp;&nbsp;
+  <a href="https://jbeirer.github.io/rootfig/gallery/#a-two-dimensional-histogram"><img src="docs/images/gallery/hist2d.png" alt="Two-dimensional histogram" width="46%"></a>
 </p>
 
 **[Explore the gallery →](https://jbeirer.github.io/rootfig/gallery/)**
@@ -55,16 +70,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 +122,10 @@ 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.
 - **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 +156,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

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

@@ -61,14 +61,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

{rootfig-0.2.2 → rootfig-0.3.0}/docs/hooks/gallery.py

@@ -60,7 +60,8 @@ def render_section(gallery: ModuleType, example: Any) -> str:
     return (
         f"## {example.title}\n\n"
         f"{example.description}\n\n"
-        f'![{example.title}](images/gallery/{example.name}.png){{ width="75%" }}\n\n'
+        f"![{example.title}](images/gallery/{example.name}.png)"
+        f'{{ width="{example.image_width}" }}\n\n'
         f"```python\n{code}```\n"
     )
 

{rootfig-0.2.2 → rootfig-0.3.0}/docs/plotting.md

@@ -86,12 +86,98 @@ shorter `ratio_label` such as `"Ratio"` to keep it at full size. The
 computed values are returned in `Plot.ratios` as
 [`Ratio`][rootfig.Ratio] objects (`values`, `errors`, `band`, `edges`).
 
+## Binning and range
+
+`bins` takes an `int`, a `(n, low, high)` triple, a sequence of edges or a
+`hist` axis, and is shared by every sample of one plot (and by the numerator
+and denominator of an [efficiency](#efficiencies)).
+
+With an integer `bins` the range comes from `range`:
+
+| `range` | Meaning |
+| --- | --- |
+| `(low, high)` | explicit |
+| `"robust"` | **default**: the min/max of the data, ignoring values far from the bulk |
+| `"auto"` | the full finite minimum and maximum over all samples |
+
+```python
+rf.plot("events.root", "d0_significance", bins=50)  # robust
+rf.plot("events.root", "d0_significance", bins=50, range="auto")  # full extent
+rf.plot("events.root", "d0_significance", bins=50, range=(-5, 5))  # explicit
+```
+
+!!! note "Rejected values are not discarded"
+
+    A value outside the range is **not removed from the data**: it goes to the
+    under/overflow, shown by the flow arrows (`flow="show"` turns them into
+    visible bins, `flow="sum"` folds them into the edge bins). Statistics boxes
+    and `rf.summarize` are computed before binning, so means and entry counts
+    cover the full sample whichever range is used.
+
+This happens in two steps. Outliers are rejected by their modified z-score
+(`0.6745 * |x - median| / MAD`), with a threshold of 30, which removes sentinels
+and anything else far from the bulk. That is done within each sample, and the
+ranges they keep are unioned, so a sample is judged against its own median and
+spread: a signal offset from a background is not an outlier merely because the
+background outnumbers it, and a sample keeps the same values whether it is
+plotted alone or in an overlay. The threshold is then tightened for as
+long as each step costs no more than an *additional* 1 percent of any one
+sample, by entries and by weight. Additional is meant literally: the budget is
+measured against what the first step already moved out of the view, which may
+be a good deal more than 1 percent. This second step cuts a tail that reaches
+far but thins out smoothly, the kind a distance threshold keeps and that leaves
+the interesting part of the distribution in a corner of the axis.
+
+The budget is charged per sample rather than over the pooled entries, so a small
+signal sitting far from a large background keeps its own place on the axis
+instead of being cut as a rounding error, and it is charged against the weight a
+cut would remove as well as the entries, so a handful of high-weight entries is
+not treated as negligible. A sample with fewer than 20 distinct values is
+categorical — counts, flags, multiplicities — has no tail to cut and gets no
+budget at all, so the second step takes no value off its axis; this is decided
+per sample too, and holds when it is overlaid with a continuous one. If MAD is zero, the mean absolute deviation from
+the median is used instead. Every candidate is padded by 5 percent and clamped
+to the `"auto"` range (whose upper edge is nudged above the maximum to include
+it), so the range never reaches past the data. Degenerate ranges are widened
+symmetrically. The threshold cannot distinguish sentinels from valid data.
+Cases where you may want `range="auto"`:
+
+- a distribution with a long tail (log-normal, Student-t, or an invariant mass
+  with a continuum) has valid tail entries pushed into the flow bins — this is
+  what the second step is for, so `"auto"` is the way to see the whole tail;
+- a sparse discrete distribution can lose rare valid values from the visible
+  range, for example the ones in a binary sample with 999 zeros and one one;
+- a lone value far from a bulk of near-identical ones looks exactly like a
+  sentinel and is rejected with them, however real it is;
+- `xbreak=(a, b)` is validated against the inferred axis, so a break meant to
+  span a far tail needs `range="auto"` or an explicit range.
+
+Inferring a robust range requires additional median and deviation calculations
+over the combined samples, with additional time and memory costs. An explicit
+range avoids range inference.
+
+!!! tip "The plot is mostly empty space"
+
+    The inferred range cuts a thin tail, but only as far as its coverage
+    budget allows. A distribution whose tail carries more than that — a heavy
+    Student-t, a steeply falling spectrum over several decades — still spreads
+    the axis over bins holding a fraction of a percent of the peak. Three ways
+    out, in order of how often they are what you want:
+
+    - `range=(a, b)` around the core. Nothing is lost: entries outside go to
+      the flow bins, where `flow="hint"` (the default) marks them with arrows
+      and `flow="sum"` folds them into the edge bins.
+    - `logy=True`, which makes the tail visible instead of hiding it.
+    - `xbreak=(a, b)` to cut the empty middle out and keep both ends, with
+      `range="auto"` or an explicit range so the break lies inside the axis.
+
 ## Axes
 
 - `logx`, `logy`: logarithmic scales. Log-spaced bins: `bins=rf.log_bins(n, low, high)`.
 - `xlim`, `ylim`: limits; `ylim=(None, 1e4)` keeps the automatic lower value.
-  Automatic y limits leave room for the legend and label (a factor 1.45 in
-  linear scale, 30 in log scale).
+  Automatic y limits add a small margin above the tallest bin (a factor 1.2 in
+  linear scale, 12 in log scale) and then raise it further as the drawn
+  legend, label, statistics box and text lines need.
 - `xbreak=(a, b)`: cut the range between `a` and `b` out of the x axis and
   draw the two remaining segments side by side with break marks, sharing the
   y axis (and the ratio panel, if any). Useful for a peak plus a far tail or
@@ -99,7 +185,8 @@ computed values are returned in `Plot.ratios` as
   (`Plot.ratio_ax_right`). Not available together with `ax=` or `flow="show"`.
 
   ![Broken x axis with a ratio panel](images/gallery/xbreak_ratio.png){ width="60%" }
-- `flow`: how under/overflow is shown, `"hint"` (small arrows, default),
+- `flow`: how under/overflow is shown (this is where entries outside an
+  inferred [range](#binning-and-range) end up), `"hint"` (small arrows, default),
   `"show"` (extra bins labelled `<low` / `>high`, added on a side as soon as any
   sample has content there, identical for all samples and the ratio panel),
   `"sum"` (added to the edge bins before anything is computed, so ratios,
@@ -110,9 +197,11 @@ computed values are returned in `Plot.ratios` as
 - `xlabel`, `ylabel`, `unit`, `title`. The title sits above the axes, where
   the CMS-style label is also drawn; with such a style prefer `text=`.
 - Automatic y limits leave room for the legend, the experiment label, the
-  statistics box and `text` lines: the upper limit is raised until none of
-  them covers a histogram (the legend picks a free upper corner). A `ylim`
-  with an explicit upper value switches this off.
+  statistics box and `text` lines: a small fixed margin is added above the
+  tallest bin, and the upper limit is then raised until none of them covers a
+  histogram (the legend picks a free upper corner). Room is only made for
+  what is actually drawn, so a plot without annotations keeps the margin.
+  A `ylim` with an explicit upper value switches this off.
 
 ## Legend, labels, text and statistics
 

{rootfig-0.2.2 → rootfig-0.3.0}/docs/quickstart.md

@@ -19,6 +19,11 @@ the weight (nothing else), evaluates them, fills a `hist.Hist` and draws it.
 If the file contains exactly one tree you can leave `tree` out. The file can
 also be a glob (`"run_*.root"`), a list of files, or `"file.root:tree"`.
 
+A bare `bins=50` infers the range from the data, ignoring far outliers so that
+sentinel values such as `-999` do not set the axis; pass `range=(low, high)` to
+be explicit or `range="auto"` for the full extent (see
+[Binning and range](plotting.md#binning-and-range)).
+
 The return value is a [`Plot`][rootfig.Plot] with `fig`, `ax`, `hists` and a
 `save()` method:
 

{rootfig-0.2.2 → rootfig-0.3.0}/examples/gallery/__init__.py

@@ -125,15 +125,16 @@ def quick() -> rf.Plot:
 @example("overlay_ratio", "Several samples, normalised, with a ratio panel")
 def overlay_ratio() -> rf.Plot:
     """A ``{label: file}`` mapping gives one histogram per sample with a binning shared by
-    all. ``normalize=True`` scales each to unit area and ``ratio=True`` adds a panel with
-    every sample divided by the first, uncertainties propagated."""
+    all. An integer ``bins`` infers the range from every sample at once, cutting the thin
+    end of the tail. ``normalize=True`` scales each to unit area and ``ratio=True`` adds a
+    panel with every sample divided by the first, uncertainties propagated."""
     return rf.plot(
         {"Signal": "signal.root", "Z + jets": "background.root"},
         "Muon_pt",
         tree="events",
         selection="Muon_isTight and abs(Muon_eta) < 2.5",
         weight="weight",
-        bins=(40, 0, 400),
+        bins=40,
         unit="GeV",
         normalize=True,
         ratio=True,
@@ -204,17 +205,21 @@ def log_axes(signal: rf.Sample, zjets: rf.Sample, diboson: rf.Sample) -> rf.Plot
     )
 
 
-@example("robust_range", "Automatic ranges: full versus robust")
+@example(
+    "robust_range",
+    "Automatic ranges: robust by default, or the full extent",
+    image_width="100%",
+)
 def robust_range(signal: rf.Sample, zjets: rf.Sample) -> rf.Plot:
-    """Sentinels such as ``-999`` wreck an automatic range. ``range="robust"`` ignores far
-    outliers when choosing the range (nothing is removed from the data, they end up in the
-    underflow). Passing ``ax=`` draws into your own axes, so two rootfig plots share one
-    figure."""
+    """Sentinels such as ``-999`` wreck an automatic range, so an integer ``bins`` without an
+    explicit range infers one robustly: far outliers are ignored when choosing the axis, and
+    the thin end of a tail is cut as long as few entries leave the view (nothing is removed
+    from the data, it ends up in the flow bins, where the arrows point at it).
+    ``range="auto"`` asks for the full finite minimum and maximum instead. Passing ``ax=``
+    draws into your own axes, so two rootfig plots share one figure."""
     _, (left, right) = plt.subplots(1, 2, figsize=(11, 4.2))
     rf.plot([signal, zjets], "lep_iso", bins=40, range="auto", ax=left, title='range="auto"')
-    return rf.plot(
-        [signal, zjets], "lep_iso", bins=40, range="robust", ax=right, title='range="robust"'
-    )
+    return rf.plot([signal, zjets], "lep_iso", bins=40, ax=right, title="default (robust)")
 
 
 @example("xbreak_ratio", "A broken x axis: peak and far tail without the empty middle")
@@ -233,6 +238,7 @@ def xbreak_ratio(
         logy=True,
         xbreak=(125, 195),
         style=atlas,
+        figsize=(7, 5.6),
     )
 
 
@@ -339,27 +345,31 @@ def arrays() -> rf.Plot:
 def hist2d(signal: rf.Sample, met: rf.Variable) -> rf.Plot:
     """``rf.plot2d`` fills a 2D histogram of one sample; both variables must have the same
     structure (both per-event here). ``logz`` and ``cmap`` control the colour scale."""
-    return rf.plot2d(
+    p = rf.plot2d(
         signal,
         rf.Variable("sum(Jet_pt)", bins=(40, 0, 800), label=r"$H_T$", unit="GeV"),
         met,
         selection="nJet >= 2",
         logz=True,
         cmap="magma",
-        zlabel="Events",
     )
+    p.fig.axes[-1].set_ylabel("")  # Omit the colour-bar title in this gallery layout.
+    return p
 
 
 @example("correlation", "A correlation matrix")
 def correlation(signal: rf.Sample) -> rf.Plot:
     """``rf.correlation`` computes the (weighted) linear correlation of several per-event
     quantities and draws it as an annotated matrix; ``percent=True`` labels cells in percent."""
-    return rf.correlation(
+    p = rf.correlation(
         signal,
         ["MET", "sum(Jet_pt)", "nJet", "nMuon", "m_ll"],
         labels=[r"$E_T^{miss}$", r"$H_T$", r"$N_{jet}$", r"$N_{\mu}$", r"$m_{\ell\ell}$"],
         percent=True,
+        figsize=(7, 5.6),
     )
+    p.fig.axes[-1].set_ylabel("")  # Omit the colour-bar title in this gallery layout.
+    return p
 
 
 @example("luminosity", "Cross sections and a luminosity instead of hand-made scale factors")

{rootfig-0.2.2 → rootfig-0.3.0}/examples/gallery/registry.py

@@ -27,6 +27,7 @@ class Example:
     name: str
     title: str
     func: Callable[..., rf.Plot]
+    image_width: str = "75%"
 
     @property
     def description(self) -> str:
@@ -47,11 +48,13 @@ class Example:
 EXAMPLES: list[Example] = []
 
 
-def example(name: str, title: str) -> Callable[[Callable[..., rf.Plot]], Callable[..., rf.Plot]]:
+def example(
+    name: str, title: str, *, image_width: str = "75%"
+) -> Callable[[Callable[..., rf.Plot]], Callable[..., rf.Plot]]:
     """Register a gallery example."""
 
     def register(func: Callable[..., rf.Plot]) -> Callable[..., rf.Plot]:
-        EXAMPLES.append(Example(name, title, func))
+        EXAMPLES.append(Example(name, title, func, image_width=image_width))
         return func
 
     return register

{rootfig-0.2.2 → rootfig-0.3.0}/src/rootfig/__init__.py

@@ -52,7 +52,7 @@ from rootfig.histograms import (
 from rootfig.model import Cut, Sample, Style, Variable, log_bins
 from rootfig.plotting import Plot, use_style
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"
 
 __all__ = [
     "BinningError",