---
name: mplhep
description: >-
  Use when plotting HEP histograms with matplotlib and mplhep: applying a
  stable experiment style such as LHCb2, adding LHCb labels, drawing 1D or 2D
  histograms, and constructing data/model comparisons or ratio panels.
---

# mplhep

Use mplhep for pre-binned NumPy or UHI-compatible histograms. Match the label,
status text, energy, luminosity, and data/simulation designation to the actual
sample and the collaboration's current publication policy.

## Minimal LHCb plot

```python
import matplotlib.pyplot as plt
import mplhep as mh

mh.style.use("LHCb2")

fig, ax = plt.subplots()
mh.histplot(histogram, ax=ax, histtype="errorbar", label="Data")
mh.lhcb.label("Preliminary", data=True, ax=ax)
ax.set(xlabel=r"$m(K\pi)$ [MeV/$c^2$]", ylabel="Candidates / bin")
ax.legend()
fig.savefig("mass.pdf")
```

`LHCb2` is a stable named mplhep style. It is LHCb-like rather than an official
replacement for collaboration plotting requirements.

## Comparisons

- Use `mh.histplot` for NumPy `(values, edges)`, boost-histogram, or `hist.Hist`
  inputs.
- Use `mh.hist2dplot` for two-dimensional binned data.
- Build ratio or pull panels with shared x-axes and propagate numerator and
  denominator uncertainties. Define behavior for zero-denominator bins.
- Distinguish data, simulation, and fit components visually and in the label.
- State units, bin-width normalization, and overflow treatment.

Call `mh.mpl_magic(soft_fail=True)` only when labels or legends need automatic
axis fitting; inspect the saved output rather than assuming the layout is
correct. Use the current [mplhep guide](https://mplhep.readthedocs.io/) for
style and label parameters.