Utilities¤
This section covers advanced mplhep features and utilities.
Prerequisites
Throughout this guide the following codeblock is assumed.
Text placement¤
Add text¤
mh.add_text will add text to a specified location on the axis. It has flexible positioning options, that are accessible via the loc argument, or the x and y arguments.
fig, ax = plt.subplots()
positions = [
("right_in", "top_in"),
("left_in", "top_in"),
("left_in", "bottom_in"),
("right_in", "bottom_in"),
("right", "top_out"),
("left", "top_out"),
("right_out", "top_in"),
("right_out", "bottom_in"),
("right", "bottom_out"),
("left", "bottom_out"),
]
for x, y in positions:
mh.add_text(
f'Text with\nx="{x}"\ny="{y}"',
x=x,
y=y,
ax=ax,
)
fig, ax = plt.subplots()
positions = [
("right_in", "top_in"),
("left_in", "top_in"),
("left_in", "bottom_in"),
("right_in", "bottom_in"),
("right", "top_out"),
("left", "top_out"),
("right_out", "top_in"),
("right_out", "bottom_in"),
("right", "bottom_out"),
("left", "bottom_out"),
]
for x, y in positions:
mh.add_text(
f'Text with\nx="{x}"\ny="{y}"',
x=x,
y=y,
ax=ax,
)
fig, ax = plt.subplots()
positions = [
("right_in", "top_in"),
("left_in", "top_in"),
("left_in", "bottom_in"),
("right_in", "bottom_in"),
("right", "top_out"),
("left", "top_out"),
("right_out", "top_in"),
("right_out", "bottom_in"),
("right", "bottom_out"),
("left", "bottom_out"),
]
for x, y in positions:
mh.add_text(
f'Text with\nx="{x}"\ny="{y}"',
x=x,
y=y,
ax=ax,
)
fig, ax = plt.subplots()
positions = [
("right_in", "top_in"),
("left_in", "top_in"),
("left_in", "bottom_in"),
("right_in", "bottom_in"),
("right", "top_out"),
("left", "top_out"),
("right_out", "top_in"),
("right_out", "bottom_in"),
("right", "bottom_out"),
("left", "bottom_out"),
]
for x, y in positions:
mh.add_text(
f'Text with\nx="{x}"\ny="{y}"',
x=x,
y=y,
ax=ax,
)
fig, ax = plt.subplots()
positions = [
("right_in", "top_in"),
("left_in", "top_in"),
("left_in", "bottom_in"),
("right_in", "bottom_in"),
("right", "top_out"),
("left", "top_out"),
("right_out", "top_in"),
("right_out", "bottom_in"),
("right", "bottom_out"),
("left", "bottom_out"),
]
for x, y in positions:
mh.add_text(
f'Text with\nx="{x}"\ny="{y}"',
x=x,
y=y,
ax=ax,
)
fig, ax = plt.subplots()
positions = [
("right_in", "top_in"),
("left_in", "top_in"),
("left_in", "bottom_in"),
("right_in", "bottom_in"),
("right", "top_out"),
("left", "top_out"),
("right_out", "top_in"),
("right_out", "bottom_in"),
("right", "bottom_out"),
("left", "bottom_out"),
]
for x, y in positions:
mh.add_text(
f'Text with\nx="{x}"\ny="{y}"',
x=x,
y=y,
ax=ax,
)
fig, ax = plt.subplots()
positions = [
("right_in", "top_in"),
("left_in", "top_in"),
("left_in", "bottom_in"),
("right_in", "bottom_in"),
("right", "top_out"),
("left", "top_out"),
("right_out", "top_in"),
("right_out", "bottom_in"),
("right", "bottom_out"),
("left", "bottom_out"),
]
for x, y in positions:
mh.add_text(
f'Text with\nx="{x}"\ny="{y}"',
x=x,
y=y,
ax=ax,
)
Append text¤
mh.append_text appends additional text relative to an existing text object created with mh.add_text. The new text can be positioned above, below, left, or right of the existing text.
# Add text at specific location
txt = mh.add_text('Custom Text', loc='upper right')
# Append additional text
mh.append_text('Additional info', txt, loc='below')
Subplot creation¤
mh.subplots is a wrapper around plt.subplots to create a figure with multiple subplots. It conveniently adjusts the figure size and spacing between subplots if multiple rows are requested.
fig, axes = mh.subplots(nrows=6)
# Will scale the figure, and add spacing between rows and remove the xlabels on inner plots.
Save variations¤
mh.savelabels automatically generates multiple versions of a plot with different experiment label text variations, useful for creating preliminary and final versions of plots.
mh.savelabels('test.png')
# Produces: test.png, test_pas.png, test_supp.png, test_wip.png, with no label, 'Preliminary', 'Supplementary', and 'Work in Progress' labels respectively.
mh.savelabels('test', labels=[("FOO", "foo.pdf"), ("BAR", "bar")])
# Produces: foo.pdf, test_bar.png
Fit y-label¤
mh.set_fitting_ylabel_fontsize adjusts the y-axis label font size to fit within the figure when there are long y-axis labels.
mpl_magic¤
The function mh.mpl_magic applies several common mplhep utilities to a given axis:
- mh.set_ylow: Sets a minimum y-axis limit based on data.
- mh.yscale_legend: Rescales the y-axis to fit the legend.
- mh.yscale_anchored_text: Rescales the y-axis to fit anchored text.
You can also call these functions individually as needed.
Axes manipulation¤
Add colorbar axis¤
mh.make_square_add_cbar creates a square axis and adds a colorbar axis to the right, useful for 2D histograms.
Add axis¤
mh.append_axes appends a new axis to an existing axis in a specified direction (top, bottom, left, right).
ax_new = mh.append_axes(ax, position='top', size=2, pad=0.3)
# Adds a new axis above ax with height 2 inches and 0.3 inch padding.
plt.hist wrapper¤
mh.hist is a drop-in replacement for mh.histplot which runs the np.histogram function before plotting. It provides a convenient way to create a histogram of raw data values and benefits from the extended features of mh.histplot, such as automatic error bar calculation, bin-width normalization and HEP-style plotting options.
Warning
mh.hist does not return a histogram object compatible with the Unified Histogram Interface (UHI), thus cannot be used directly with other mplhep histogram plotting functions.