rootfig 0.7.1

Publication-quality figures straight from ROOT trees, without ROOT.

Documentation · Gallery · Quick start

Go from a ROOT file to a styled figure in one call. Choose a variable, add a selection, and plot:

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.

Explore the gallery → See each figure alongside the code that makes it, from simple overlays to stacked data/MC comparisons, broken axes and 2D histograms, in the neutral style or in that of ATLAS, CMS, LHCb, ALICE or DUNE.

Installation

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

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:

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.

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:

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")

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:

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:

book = rf.PlotBook(
    [vv, signal],
    variables=rf.ALL,
    exclude=["*_cov", "*Index"],
)

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. 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 combined statistical and systematic band, and every component stays accessible.
• Style figures for your analysis. Add experiment labels, units, log axes and broken axes, then refine the result with matplotlib.
• Produce whole sets of plots. rf.PlotBook runs one rf.plot call over variables × selections × variants, lazily, and saves each under a deterministic name or all of them as one multipage PDF; rf.ALL discovers the variables from the files, and select() filters the book down while iterating on a plot.
• Go beyond 1D plots. Draw 2D histograms, correlations, efficiencies, profiles, resolutions and significance panels; produce cut flows and summary statistics from the same inputs.
• 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 or browse the gallery for examples with figures and code.

• Quick start: your first plot, selections and weights.
• Expressions and selections: syntax and event/object rules.
• Samples, variables, cuts and styles: reusable analysis definitions.
• Plotting options: binning, normalisation, panels and styling.
• API reference: 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:

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 for details.

Development

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 for details.

Citation

If rootfig is useful in your research, please cite it:

@software{rootfig,
  author = {Beirer, Joshua Falco},
  doi = {10.5281/zenodo.22726311},
  license = {MIT},
  title = {{rootfig}},
  url = {https://github.com/jbeirer/rootfig},
  year = {2026}
}

License

MIT. See LICENSE.