mplhep: Matplotlib styles for HEP

mplhep is a matplotlib wrapper designed to simplify the plotting requirements common in High Energy Physics (HEP).

Key features include:

• Easy plotting of "prebinned" 1D and 2D histograms.
• Matplotlib style-sheets that implement the recommended plotting styles used by major LHC experiments, specifically ATLAS, CMS, and LHCb.

The mplhep documentation is organized into several functional areas:

• Histogram Plotting: Functions for 1D and 2D pre-binned histograms, including support for the Unified Histogram Interface (UHI). Topics include supported input formats, histogram styles, multiple histograms, blinding, error bars, and normalization.
• Comparison Plotting: High-level functions for comparing data models, such as comparing two histograms or performing Data-MC comparisons.
• Styling: Tools for applying official experiment styles (ATLAS, CMS, LHCb, ALICE, and DUNE) and configuring experiment labels.
• Utilities: Helper functions for text placement, subplot creation, saving variations, fitting y-labels, axes manipulation, and a plt.hist wrapper.
• Advanced Topics: Deep dives into UHI integration and best practices.

The ATLAS experiment has two primary recommended styles in mplhep:

1. ATLAS or ATLAS2: The main recommendation. It provides a palette of 7 colors. The first color, Vermilion, is specifically recommended for representing signal. For large signals, white can also be used.
2. ATLAS1: Provided for plots that require a larger number of colors (10 colors total).

Use mplhep.style.use("ATLAS2") for standard signal plots and mplhep.style.use("ATLAS1") when you need more distinct colors.

import mplhep

# Use the standard 7-color palette
mplhep.style.use("ATLAS2")

# Use the 10-color palette for complex plots
# mplhep.style.use("ATLAS1")

LHCb has two available styles:

• LHCb1: The older style.
• LHCb2: The newer style.

Use mplhep.style.use("LHCb2") for current standard plots, or LHCb1 if you need to match older publication styles.

import mplhep

# Use the newer LHCb style
mplhep.style.use("LHCb2")

The blind parameter can be used in mh.comp.hists() and mh.comp.data_model() to hide specific regions in both the main plot and the comparison panel. This is useful for blind analyses where a signal region must remain hidden.

Pass a tuple (lower_bound, upper_bound) to the blind argument to specify the range to be hidden.

# Blinding in a two-histogram comparison
fig, ax_main, ax_comp = mh.comp.hists(
    h1,
    h2,
    blind=(-1.0, 1.0),  # Blind the region from -1 to 1 GeV
    comparison='ratio',
    xlabel='Observable [GeV]',
    ylabel='Events'
)

You can customize the information displayed in experiment labels.

• Common configurations: Use standard parameters to combine multiple pieces of information (like name, status, and run info).
• Full customization: For complete control over the text content, use llabel (left label) and rlabel (right label) parameters.

# Example of conceptual customization
# mh.cms_label(ax, llabel='Custom Left Text', rlabel='Custom Right Text')

For the DUNE neutrino experiment, there are two ways to access styles:

• DUNE: This is a pointer to the newest available style. Use this to ensure your plots always use the most up-to-date styling as mplhep is updated.
• DUNE1: Use this if you need to ensure backwards compatibility and want to prevent your plot styles from changing when the experiment updates its recommendations.

import mplhep

# Always use the latest DUNE style
mplhep.style.use("DUNE")

# Use DUNE1 for stable, backwards-compatible styling
# mplhep.style.use("DUNE1")

To maintain consistency, apply your desired style (e.g., "CMS") at the beginning of your script using mh.style.use(), rather than inside plotting functions.

import mplhep as mh

# At the top of your script
mh.style.use("CMS")

# Then create all plots
# ...

Once installed, you can use mplhep to apply high-energy physics styles (like CMS, ATLAS, or LHCb2) to your Matplotlib plots and use specialized plotting functions like mh.histplot.

import numpy as np
import matplotlib.pyplot as plt
import mplhep as mh

# Load style sheet
plt.style.use(mh.style.CMS)  # or ATLAS/LHCb2

h, bins = np.histogram(np.random.random(1000))
fig, ax = plt.subplots()
mh.histplot(h, bins)

Documentation styles are managed in generate_style_guides.py.

To update existing templates

1. Edit the docs/*_template.md file.
2. Use {{TABS_START}} and {{TABS_END}} for content that varies by style.
3. Run python generate_style_guides.py to test the generation.

To add a new style

1. Add the new style configuration to the STYLES dictionary in generate_style_guides.py.
2. Add the style name to the STYLE_ORDER list in generate_style_guides.py.
3. Run the generation script.

To modify style-specific code

1. Edit the corresponding entry in the STYLES dictionary within generate_style_guides.py.
2. Run python generate_style_guides.py to regenerate the files.

You can install mplhep using pip. Depending on your environment and permissions, use one of the following commands:

• Standard installation (system-wide or current virtual environment): pip install mplhep
• Local user installation (if you lack administrator permissions): pip install --user mplhep
• Upgrade an existing installation: pip install --upgrade mplhep

If you use Conda, activate your desired environment and use the conda-provided pip to install it.