Basic Plotting

This section covers the core plotting functionality of mplhep for plotting 1D and 2D histograms.

Prerequisites

Throughout this guide the following codeblock is assumed.

import matplotlib.pyplot as plt
import numpy as np
import hist
np.random.seed(42)
import mplhep as mh
# mh.style.use('<as appropriate>')

1D Histogram Plotting

mh.histplot() works with multiple histogram formats through the UHI protocol:

Supported Input Formats

DefaultplothistCMSATLASLHCbALICEDUNE

Array-Likenumpy.histogramhist.Histuproot.TH1

fig, ax = plt.subplots()
mh.histplot([1, 2, 3, 6, 3, 5, 2, 1], ax=ax)

data = np.random.normal(0, 1, 1000)
fig, ax = plt.subplots()
mh.histplot(*np.histogram(data, bins=40), ax=ax)

data = np.random.normal(0, 1, 1000)
h_obj = hist.new.Reg(40, -4, 4).Weight().fill(data)
fig, ax = plt.subplots()
mh.histplot(h_obj, ax=ax)
# Note that errorbars are now automatically plotted because hist.Hist inputs objects has .variances() available

import uproot

file = uproot.open(uproot_file_name)
h_root = file['hpx']
fig, ax = plt.subplots()
mh.histplot(h_root, ax=ax)

Array-Likenumpy.histogramhist.Histuproot.TH1

fig, ax = plt.subplots()
mh.histplot([1, 2, 3, 6, 3, 5, 2, 1], ax=ax)

data = np.random.normal(0, 1, 1000)
fig, ax = plt.subplots()
mh.histplot(*np.histogram(data, bins=40), ax=ax)

data = np.random.normal(0, 1, 1000)
h_obj = hist.new.Reg(40, -4, 4).Weight().fill(data)
fig, ax = plt.subplots()
mh.histplot(h_obj, ax=ax)
# Note that errorbars are now automatically plotted because hist.Hist inputs objects has .variances() available

import uproot

file = uproot.open(uproot_file_name)
h_root = file['hpx']
fig, ax = plt.subplots()
mh.histplot(h_root, ax=ax)

Array-Likenumpy.histogramhist.Histuproot.TH1

fig, ax = plt.subplots()
mh.histplot([1, 2, 3, 6, 3, 5, 2, 1], ax=ax)

data = np.random.normal(0, 1, 1000)
fig, ax = plt.subplots()
mh.histplot(*np.histogram(data, bins=40), ax=ax)

data = np.random.normal(0, 1, 1000)
h_obj = hist.new.Reg(40, -4, 4).Weight().fill(data)
fig, ax = plt.subplots()
mh.histplot(h_obj, ax=ax)
# Note that errorbars are now automatically plotted because hist.Hist inputs objects has .variances() available

import uproot

file = uproot.open(uproot_file_name)
h_root = file['hpx']
fig, ax = plt.subplots()
mh.histplot(h_root, ax=ax)

Array-Likenumpy.histogramhist.Histuproot.TH1

fig, ax = plt.subplots()
mh.histplot([1, 2, 3, 6, 3, 5, 2, 1], ax=ax)

data = np.random.normal(0, 1, 1000)
fig, ax = plt.subplots()
mh.histplot(*np.histogram(data, bins=40), ax=ax)

data = np.random.normal(0, 1, 1000)
h_obj = hist.new.Reg(40, -4, 4).Weight().fill(data)
fig, ax = plt.subplots()
mh.histplot(h_obj, ax=ax)
# Note that errorbars are now automatically plotted because hist.Hist inputs objects has .variances() available

import uproot

file = uproot.open(uproot_file_name)
h_root = file['hpx']
fig, ax = plt.subplots()
mh.histplot(h_root, ax=ax)

Array-Likenumpy.histogramhist.Histuproot.TH1

fig, ax = plt.subplots()
mh.histplot([1, 2, 3, 6, 3, 5, 2, 1], ax=ax)

data = np.random.normal(0, 1, 1000)
fig, ax = plt.subplots()
mh.histplot(*np.histogram(data, bins=40), ax=ax)

data = np.random.normal(0, 1, 1000)
h_obj = hist.new.Reg(40, -4, 4).Weight().fill(data)
fig, ax = plt.subplots()
mh.histplot(h_obj, ax=ax)
# Note that errorbars are now automatically plotted because hist.Hist inputs objects has .variances() available

import uproot

file = uproot.open(uproot_file_name)
h_root = file['hpx']
fig, ax = plt.subplots()
mh.histplot(h_root, ax=ax)

Array-Likenumpy.histogramhist.Histuproot.TH1

fig, ax = plt.subplots()
mh.histplot([1, 2, 3, 6, 3, 5, 2, 1], ax=ax)

data = np.random.normal(0, 1, 1000)
fig, ax = plt.subplots()
mh.histplot(*np.histogram(data, bins=40), ax=ax)

data = np.random.normal(0, 1, 1000)
h_obj = hist.new.Reg(40, -4, 4).Weight().fill(data)
fig, ax = plt.subplots()
mh.histplot(h_obj, ax=ax)
# Note that errorbars are now automatically plotted because hist.Hist inputs objects has .variances() available

import uproot

file = uproot.open(uproot_file_name)
h_root = file['hpx']
fig, ax = plt.subplots()
mh.histplot(h_root, ax=ax)

Array-Likenumpy.histogramhist.Histuproot.TH1

fig, ax = plt.subplots()
mh.histplot([1, 2, 3, 6, 3, 5, 2, 1], ax=ax)

data = np.random.normal(0, 1, 1000)
fig, ax = plt.subplots()
mh.histplot(*np.histogram(data, bins=40), ax=ax)

data = np.random.normal(0, 1, 1000)
h_obj = hist.new.Reg(40, -4, 4).Weight().fill(data)
fig, ax = plt.subplots()
mh.histplot(h_obj, ax=ax)
# Note that errorbars are now automatically plotted because hist.Hist inputs objects has .variances() available

import uproot

file = uproot.open(uproot_file_name)
h_root = file['hpx']
fig, ax = plt.subplots()
mh.histplot(h_root, ax=ax)

Histogram Styles

Control the appearance with the histtype parameter. Select an experiment style and then choose a histogram type:

DefaultplothistCMSATLASLHCbALICEDUNE

StepFillErrorbarBandBarBarstep

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='step', label='Step histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='fill', alpha=0.5, label='Filled histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='errorbar', label='Data', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='band', alpha=0.5, label='Band histogram', ax=ax)
# Can be used to visualize uncertainties

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='bar', label='Bar histogram', ax=ax)
# If only one histogram is provided, it will be treated as "fill" histtype, if multiple data are given the bars are arranged side by side (see next section)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='barstep', label='Barstep histogram', ax=ax)
# If one histogram is provided, it will be treated as "step" histtype. If multiple data are given the bars are arranged side by side (see next section)

StepFillErrorbarBandBarBarstep

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='step', label='Step histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='fill', alpha=0.5, label='Filled histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='errorbar', label='Data', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='band', alpha=0.5, label='Band histogram', ax=ax)
# Can be used to visualize uncertainties

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='bar', label='Bar histogram', ax=ax)
# If only one histogram is provided, it will be treated as "fill" histtype, if multiple data are given the bars are arranged side by side (see next section)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='barstep', label='Barstep histogram', ax=ax)
# If one histogram is provided, it will be treated as "step" histtype. If multiple data are given the bars are arranged side by side (see next section)

StepFillErrorbarBandBarBarstep

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='step', label='Step histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='fill', alpha=0.5, label='Filled histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='errorbar', label='Data', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='band', alpha=0.5, label='Band histogram', ax=ax)
# Can be used to visualize uncertainties

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='bar', label='Bar histogram', ax=ax)
# If only one histogram is provided, it will be treated as "fill" histtype, if multiple data are given the bars are arranged side by side (see next section)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='barstep', label='Barstep histogram', ax=ax)
# If one histogram is provided, it will be treated as "step" histtype. If multiple data are given the bars are arranged side by side (see next section)

StepFillErrorbarBandBarBarstep

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='step', label='Step histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='fill', alpha=0.5, label='Filled histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='errorbar', label='Data', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='band', alpha=0.5, label='Band histogram', ax=ax)
# Can be used to visualize uncertainties

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='bar', label='Bar histogram', ax=ax)
# If only one histogram is provided, it will be treated as "fill" histtype, if multiple data are given the bars are arranged side by side (see next section)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='barstep', label='Barstep histogram', ax=ax)
# If one histogram is provided, it will be treated as "step" histtype. If multiple data are given the bars are arranged side by side (see next section)

StepFillErrorbarBandBarBarstep

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='step', label='Step histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='fill', alpha=0.5, label='Filled histogram', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='errorbar', label='Data', ax=ax)

h = hist.new.Reg(40, -4, 4).Weight().fill(np.random.normal(0, 1, 1000))
fig, ax = plt.subplots()
mh.histplot(h, histtype='band', alpha=0.5, label='Band histogram', ax=ax)
# Can be used to visualize uncertainties