---

name: hist description: Use when working with the scikit-hep hist library in Python to create, fill, slice, and plot histograms (1D/2D/multi-axis), including UHI indexing, categorical axes, and mplhep plotting conventions.

Hist

Overview

Use this skill to build and manipulate hist.Hist objects, choose axis/storage types, fill with data and weights, and produce publication-style plots with mplhep styles, all based on matplotlib.

Quick start

• Create histograms with Hist.new plus axis builders (Reg, Var, StrCat) and finish with exactly one storage (Int64 or Weight).
• Make sure axis labels contain a short variable name and units. Histogram titles should contains a slightly longer concise description of what data went into the plot.
• Fill with .fill(...) using axis names; note that .fill returns None.
• Slice or project with UHI indexing (e.g., h.project("x") or h[{"x": 5j}]).
• Plot with hist.plot(...) or mplhep.hist2dplot(...); use plt.style.use(hep.style.ATLAS) for HEP-style plots.

Core tasks

Create axes and storage

• Use Reg for uniform bins and Var for variable-width bins.
• Use StrCat for categorical axes; set growth=True for auto-added categories.
• Choose storage: Int64 for unweighted counts, Weight for weighted fills.

Fill and access contents

• Fill with named axes (e.g., h.fill(x=..., y=..., weight=...)).
• Read counts with h.view() and errors from np.sqrt(h.variances()).

Slice, rebin, and project

• Use UHI slicing (complex numbers for bin selection, ::2j for rebinning).
• Project with h.project("axis_name") for 1D plots.

Plot and save

• Use hist.plot(histtype="fill") for 1D; use mplhep.hist2dplot for 2D.
• Use plt.subplots() without custom figsize unless explicitly requested.
• Save with fig.savefig("name.png") and close with plt.close(fig).

References

• Use references/hist-hints.md for concrete code snippets and common patterns.
• Use references/hist-advanced.md for UHI indexing, plotting gotchas, and label/LaTeX guidance.
• Use references/lhc-hist-ranges.md for starting suggestions on histogram axis ranges and binning.