rootfig 0.2.1__tar.gz → 0.3.0__tar.gz

rootfig-0.3.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: rootfig
+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/
+Project-URL: Repository, https://github.com/jbeirer/rootfig
+Project-URL: Issues, https://github.com/jbeirer/rootfig/issues
+Author-email: Joshua Falco Beirer <jbeirer@cern.ch>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: HEP,RNTuple,ROOT,TTree,awkward,histogram,matplotlib,mplhep,plotting,uproot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+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: matplotlib>=3.11
+Requires-Dist: mplhep>=1.3
+Requires-Dist: numpy>=1.26
+Requires-Dist: uproot>=5.7.4
+Description-Content-Type: text/markdown
+
+<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>
+
+<p align="center">
+  <strong>Publication-quality figures straight from ROOT trees, without ROOT.</strong>
+</p>
+
+<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>
+
+<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 a ROOT file to a styled figure in one call. Choose a variable, add a
+selection, and plot:
+
+```python
+import rootfig as rf
+
+rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=50)
+```
+
+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.
+
+<p align="center">
+  <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/#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/)**
+See each figure alongside the code that makes it, from simple overlays to
+stacked data/MC comparisons, broken axes and 2D histograms.
+
+## Installation
+
+```bash
+pip install rootfig
+# or
+uv add rootfig
+```
+
+Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
+files are both supported.
+
+## Compare samples in one call
+
+```python
+import rootfig as rf
+
+# Overlay two samples, each normalised to unity, with a Signal / Background panel.
+rf.plot(
+    {"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="Background",
+)
+```
+
+## Build up to a full analysis
+
+Define samples, variables, cuts and styles once, then reuse them across plots:
+
+```python
+import rootfig as rf
+
+signal = rf.Sample("sig_*.root", tree="events", label="Signal", weight="mc_weight")
+background = rf.Sample("bkg.root", tree="events", label="Background", weight="mc_weight")
+data = rf.Sample("data.root", tree="events", label="Data", is_data=True)
+
+pt = rf.Variable("Muon_pt", bins=(50, 0, 200), label=r"$p_T^{\mu}$", unit="GeV")
+baseline = rf.Cut("nMuon >= 1") & "abs(Muon_eta) < 2.5"
+style = rf.Style(experiment="ATLAS", status="Internal", lumi=140, com=13.6)
+
+p = rf.plot(
+    [background, signal],
+    pt,
+    observed=data,
+    selection=baseline,
+    stack=True,
+    ratio=True,
+    logy=True,
+    style=style,
+)
+p.ax.set_ylim(top=1e5)  # it is a normal matplotlib Axes
+p.save("muon_pt.pdf")
+```
+
+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.
+
+## 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
+  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,
+  profiles, resolutions and significance panels; produce cut flows and
+  summary statistics from the same inputs.
+- **Work directly with your files.** Read `TTree` and `RNTuple` data, combine
+  files with globs, limit entry ranges for quick checks, and use EDM4hep
+  split collections. Only the branches your expressions need are read.
+
+## Documentation
+
+**[Read the docs](https://jbeirer.github.io/rootfig/)** or
+**[browse the gallery](https://jbeirer.github.io/rootfig/gallery/)** for examples
+with figures and code.
+
+- [Quick start](https://jbeirer.github.io/rootfig/quickstart/): your first plot, selections and weights.
+- [Expressions and selections](https://jbeirer.github.io/rootfig/expressions/): syntax and event/object rules.
+- [Samples, variables, cuts and styles](https://jbeirer.github.io/rootfig/composable/): reusable analysis definitions.
+- [Plotting options](https://jbeirer.github.io/rootfig/plotting/): binning, normalisation, panels and styling.
+- [API reference](https://jbeirer.github.io/rootfig/api/): full signatures and options.
+
+## Relation to the ecosystem
+
+`rootfig` brings a `TTree::Draw`-like workflow to the Scientific Python HEP
+stack, building on familiar libraries:
+
+| Task | Library | What rootfig adds |
+| --- | --- | --- |
+| 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, 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
+[the ecosystem guide](https://jbeirer.github.io/rootfig/ecosystem/) for details.
+
+## Development
+
+```bash
+git clone https://github.com/jbeirer/rootfig
+cd rootfig
+uv sync --all-groups
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

rootfig-0.3.0/README.md

@@ -0,0 +1,181 @@
+<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>
+
+<p align="center">
+  <strong>Publication-quality figures straight from ROOT trees, without ROOT.</strong>
+</p>
+
+<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>
+
+<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 a ROOT file to a styled figure in one call. Choose a variable, add a
+selection, and plot:
+
+```python
+import rootfig as rf
+
+rf.plot("events.root", "Muon_pt", tree="events", selection="Muon_pt > 20", bins=50)
+```
+
+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.
+
+<p align="center">
+  <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/#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/)**
+See each figure alongside the code that makes it, from simple overlays to
+stacked data/MC comparisons, broken axes and 2D histograms.
+
+## Installation
+
+```bash
+pip install rootfig
+# or
+uv add rootfig
+```
+
+Python 3.12 or newer. No ROOT installation is needed; `TTree` and `RNTuple`
+files are both supported.
+
+## Compare samples in one call
+
+```python
+import rootfig as rf
+
+# Overlay two samples, each normalised to unity, with a Signal / Background panel.
+rf.plot(
+    {"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="Background",
+)
+```
+
+## Build up to a full analysis
+
+Define samples, variables, cuts and styles once, then reuse them across plots:
+
+```python
+import rootfig as rf
+
+signal = rf.Sample("sig_*.root", tree="events", label="Signal", weight="mc_weight")
+background = rf.Sample("bkg.root", tree="events", label="Background", weight="mc_weight")
+data = rf.Sample("data.root", tree="events", label="Data", is_data=True)
+
+pt = rf.Variable("Muon_pt", bins=(50, 0, 200), label=r"$p_T^{\mu}$", unit="GeV")
+baseline = rf.Cut("nMuon >= 1") & "abs(Muon_eta) < 2.5"
+style = rf.Style(experiment="ATLAS", status="Internal", lumi=140, com=13.6)
+
+p = rf.plot(
+    [background, signal],
+    pt,
+    observed=data,
+    selection=baseline,
+    stack=True,
+    ratio=True,
+    logy=True,
+    style=style,
+)
+p.ax.set_ylim(top=1e5)  # it is a normal matplotlib Axes
+p.save("muon_pt.pdf")
+```
+
+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.
+
+## 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
+  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,
+  profiles, resolutions and significance panels; produce cut flows and
+  summary statistics from the same inputs.
+- **Work directly with your files.** Read `TTree` and `RNTuple` data, combine
+  files with globs, limit entry ranges for quick checks, and use EDM4hep
+  split collections. Only the branches your expressions need are read.
+
+## Documentation
+
+**[Read the docs](https://jbeirer.github.io/rootfig/)** or
+**[browse the gallery](https://jbeirer.github.io/rootfig/gallery/)** for examples
+with figures and code.
+
+- [Quick start](https://jbeirer.github.io/rootfig/quickstart/): your first plot, selections and weights.
+- [Expressions and selections](https://jbeirer.github.io/rootfig/expressions/): syntax and event/object rules.
+- [Samples, variables, cuts and styles](https://jbeirer.github.io/rootfig/composable/): reusable analysis definitions.
+- [Plotting options](https://jbeirer.github.io/rootfig/plotting/): binning, normalisation, panels and styling.
+- [API reference](https://jbeirer.github.io/rootfig/api/): full signatures and options.
+
+## Relation to the ecosystem
+
+`rootfig` brings a `TTree::Draw`-like workflow to the Scientific Python HEP
+stack, building on familiar libraries:
+
+| Task | Library | What rootfig adds |
+| --- | --- | --- |
+| 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, 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
+[the ecosystem guide](https://jbeirer.github.io/rootfig/ecosystem/) for details.
+
+## Development
+
+```bash
+git clone https://github.com/jbeirer/rootfig
+cd rootfig
+uv sync --all-groups
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

{rootfig-0.2.1 → 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.1 → 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.1 → 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.1 → 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: