Skip to content

mplhep¤

A matplotlib wrapper for easy plotting required in high energy physics (HEP). Primarily "prebinned" 1D & 2D histograms and matplotlib style-sheets carrying recommended plotting styles of large LHC experiments - ATLAS, CMS & LHCb. This project is published on GitHub.

Quick Start¤

Installation¤

Install mplhep using pip:

pip install mplhep

Simple Example¤

Here's a quick example showing the primary functionality

import matplotlib.pyplot as plt
import mplhep as mh
import numpy as np
np.random.seed(42)
# Set the plotting style
mh.style.use() # Style reset to default

# Create a plot
fig, ax = plt.subplots()
# Plot a pre-binned histogram
mh.histplot(*np.histogram(np.random.normal(0, 1, 1000)), ax=ax, label="Data")
# Add appropriate labels
txt_obj = mh.add_text("Default", loc='over left')
mh.append_text("matplotlib style", txt_obj, loc='right')

import matplotlib.pyplot as plt
import mplhep as mh
import numpy as np
np.random.seed(42)
# Set the plotting style
mh.style.use("PLOTHIST")

# Create a plot
fig, ax = plt.subplots()
# Plot a pre-binned histogram
mh.histplot(*np.histogram(np.random.normal(0, 1, 1000)), ax=ax, label="Data")
# Add appropriate labels
txt_obj = mh.add_text("PLOTHIST", loc='over left')
mh.append_text("Demo", txt_obj, loc='right', fontsize='x-small')

import matplotlib.pyplot as plt
import mplhep as mh
import numpy as np
np.random.seed(42)
# Set the plotting style
mh.style.use("CMS")

# Create a plot
fig, ax = plt.subplots()
# Plot a pre-binned histogram
mh.histplot(*np.histogram(np.random.normal(0, 1, 1000)), ax=ax, label="Data")
# Add appropriate labels
mh.cms.label("Preliminary", data=False, lumi=100, com=15) # ax can be implicit
# mh.mpl_magic(soft_fail=True)  # Autofit label - not needed

import matplotlib.pyplot as plt
import mplhep as mh
import numpy as np
np.random.seed(42)
# Set the plotting style
mh.style.use("ATLAS")

# Create a plot
fig, ax = plt.subplots()
# Plot a pre-binned histogram
mh.histplot(*np.histogram(np.random.normal(0, 1, 1000)), ax=ax, label="Data")
# Add appropriate labels
mh.atlas.label("Preliminary", data=False, lumi=100, com=15) # ax can be implicit
mh.mpl_magic(soft_fail=True) # Autofit label

import matplotlib.pyplot as plt
import mplhep as mh
import numpy as np
np.random.seed(42)
# Set the plotting style
mh.style.use("LHCb2")

# Create a plot
fig, ax = plt.subplots()
# Plot a pre-binned histogram
mh.histplot(*np.histogram(np.random.normal(0, 1, 1000)), ax=ax, label="Data")
# Add appropriate labels
mh.lhcb.label("Preliminary", data=False, lumi=100, com=15) # ax can be implicit
mh.mpl_magic(soft_fail=True) # Autofit label

import matplotlib.pyplot as plt
import mplhep as mh
import numpy as np
np.random.seed(42)
# Set the plotting style
mh.style.use("ALICE")

# Create a plot
fig, ax = plt.subplots()
# Plot a pre-binned histogram
mh.histplot(*np.histogram(np.random.normal(0, 1, 1000)), ax=ax, label="Data")
# Add appropriate labels
mh.alice.label("Preliminary", data=False, lumi=100, com=15) # ax can be implicit
mh.mpl_magic(soft_fail=True) # Autofit label

import matplotlib.pyplot as plt
import mplhep as mh
import numpy as np
np.random.seed(42)
# Set the plotting style
mh.style.use("DUNE")

# Create a plot
fig, ax = plt.subplots()
# Plot a pre-binned histogram
mh.histplot(*np.histogram(np.random.normal(0, 1, 1000)), ax=ax, label="Data")
# Add appropriate labels
mh.dune.label("Preliminary", data=False, lumi=100, com=15) # ax can be implicit
# mh.mpl_magic(soft_fail=True)  # Autofit label - not needed

This creates a simple histogram with HEP-style formatting. Check out the User Guide and the Gallery below for more advanced examples!

User Guide¤

API¤