API reference¶
Plotting functions¶
Primary functions.
-
mplhep.
histplot
(H, bins=None, *, yerr: ArrayLike | bool | None = None, w2=None, w2method=None, stack=False, density=False, binwnorm=None, histtype='step', xerr=False, label=None, sort=None, edges=True, binticks=False, ax=None, flow='hint', **kwargs)[source][source]¶ Create a 1D histogram plot from np.histogram-like inputs.
Parameters: - H (object) –
Histogram object with containing values and optionally bins. Can be:
- np.histogram tuple
- PlottableProtocol histogram object
- boost_histogram classic (<0.13) histogram object
- raw histogram values, provided bins is specified.
Or list thereof.
- bins (iterable, optional) – Histogram bins, if not part of
h
. - yerr (iterable or bool, optional) – Histogram uncertainties. Following modes are supported:
- True, sqrt(N) errors or poissonian interval when
w2
is specified - shape(N) array of for one sided errors or list thereof - shape(Nx2) array of for two sided errors or list thereof - w2 (iterable, optional) – Sum of the histogram weights squared for poissonian interval error calculation
- w2method (callable, optional) – Function calculating CLs with signature
low, high = fcn(w, w2)
. Herelow
andhigh
are given in absolute terms, not relative to w. Default isNone
. If w2 has integer values (likely to be data) poisson interval is calculated, otherwise the resulting error is symmetricsqrt(w2)
. Specifyingpoisson
orsqrt
will force that behaviours. - stack (bool, optional) – Whether to stack or overlay non-axis dimension (if it exists). N.B. in
contrast to ROOT, stacking is performed in a single call aka
histplot([h1, h2, ...], stack=True)
as opposed to multiple calls. - density (bool, optional) – If true, convert sum weights to probability density (i.e. integrates to 1
over domain of axis) (Note: this option conflicts with
binwnorm
) - binwnorm (float, optional) –
- If true, convert sum weights to bin-width-normalized, with unit equal to
- supplied value (usually you want to specify 1.)
- histtype ({'step', 'fill', 'errorbar'}, optional, default: "step") –
Type of histogram to plot:
- ”step”: skyline/step/outline of a histogram using plt.step
- ”fill”: filled histogram using plt.fill_between
- ”errorbar”: single marker histogram using plt.errorbar
- xerr (bool or float, optional) – Size of xerr if
histtype == 'errorbar'
. IfTrue
, bin-width will be used. - label (str or list, optional) – Label for legend entry.
- sort ({'label'/'l', 'yield'/'y'}, optional) – Append ‘_r’ for reverse.
- edges (bool, default: True, optional) – Specifies whether to draw first and last edges of the histogram
- binticks (bool, default: False, optional) – Attempts to draw x-axis ticks coinciding with bin boundaries if feasible.
- ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched or one is created)
- flow (str, optional { "show", "sum", "hint", "none"}) – Whether plot the under/overflow bin. If “show”, add additional under/overflow bin. If “sum”, add the under/overflow bin content to first/last bin.
- **kwargs – Keyword arguments passed to underlying matplotlib functions - {‘step’, ‘fill_between’, ‘errorbar’}.
Returns: Return type: List[Hist1DArtists]
- H (object) –
-
mplhep.
hist2dplot
(H, xbins=None, ybins=None, labels=None, cbar=True, cbarsize='7%', cbarpad=0.2, cbarpos='right', cbarextend=False, cmin=None, cmax=None, ax=None, flow='hint', **kwargs)[source][source]¶ Create a 2D histogram plot from np.histogram-like inputs.
Parameters: - H (object) –
Histogram object with containing values and optionally bins. Can be:
- np.histogram tuple
- boost_histogram histogram object
- raw histogram values as list of list or 2d-array
- xbins (1D array-like, optional, default None) – Histogram bins along x axis, if not part of
H
. - ybins (1D array-like, optional, default None) – Histogram bins along y axis, if not part of
H
. - labels (2D array (H-like) or bool, default None, optional) – Array of per-bin labels to display. If
True
will display numerical values - cbar (bool, optional, default True) – Draw a colorbar. In contrast to mpl behaviors the cbar axes is appended in such a way that it doesn’t modify the original axes width:height ratio.
- cbarsize (str or float, optional, default "7%") – Colorbar width.
- cbarpad (float, optional, default 0.2) – Colorbar distance from main axis.
- cbarpos ({'right', 'left', 'bottom', 'top'}, optional, default "right") – Colorbar position w.r.t main axis.
- cbarextend (bool, optional, default False) – Extends figure size to keep original axes size same as without cbar. Only safe for 1 axes per fig.
- cmin (float, optional) – Colorbar minimum.
- cmax (float, optional) – Colorbar maximum.
- ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched or one is created)
- flow (str, optional {"show", "sum","hint", None}) – Whether plot the under/overflow bin. If “show”, add additional under/overflow bin. If “sum”, add the under/overflow bin content to first/last bin. “hint” would highlight the bins with under/overflow contents
- **kwargs – Keyword arguments passed to underlying matplotlib function - pcolormesh.
Returns: Return type: Hist2DArtist
- H (object) –
Experiment label helpers¶
Experiment specific helpers
-
mplhep.cms.
lumitext
(text='', ax=None, fontname=None, fontsize=None)[source][source]¶ Add typical LHC experiment top-right label. Usually used to indicate year or aggregate luminosity in the plot. :param text: Secondary experiment label, typically not-bold and smaller
font-size. For example “Simulation” or “Preliminary”Parameters: - ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched)
- fontname (string, optional) – Name of font to be used.
- fontsize (string, optional) – Defines size of “secondary label”. Experiment label is 1.3x larger.
Returns: ax – A matplotlib Axes object
Return type: matplotlib.axes.Axes
-
mplhep.cms.
text
(text='', **kwargs)[source][source]¶ Add typical LHC experiment primary label to the axes. :param text: Secondary experiment label, typically not-bold and smaller
font-size. For example “Simulation” or “Preliminary”Parameters: - loc (int, optional) – Label position: - 0 : Above axes, left aligned - 1 : Top left corner - 2 : Top left corner, multiline - 3 : Split EXP above axes, rest of label in top left corner”
- ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched)
- fontname (string, optional) – Name of font to be used.
- fontsize (string, optional) – Defines size of “secondary label”. Experiment label is 1.3x larger.
- exp_weight (string, optional) – Set fontweight of <exp> label. Default “bold”.
- italic ((bool, bool), optional) – Tuple of bools to switch which label is italicized
- pad (float, optional) – Additional padding from axes border in units of axes fraction size.
Returns: ax – A matplotlib Axes <https://matplotlib.org/3.1.1/api/axes_api.html> object
Return type: matplotlib.axes.Axes
-
mplhep.cms.
label
(label=None, **kwargs)[source][source]¶ A convenience wrapper combining
<exp>.text
andlumitext
providing for the most common use cases. :param loc: Label position ofexp_text
label:- 0 : Above axes, left aligned
- 1 : Top left corner
- 2 : Top left corner, multiline
- 3 : Split EXP above axes, rest of label in top left corner”
- 4 : (1) Top left corner, but align “rlabel” underneath
Parameters: - ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched)
- data (bool, optional) – Prevents prepending “Simulation” to experiment label. Default
False
. - label (str, optional) – Text to append after <exp> (Simulation) <label>. Typically “Preliminary” “Supplementary”, “Private Work” or “Work in Progress”
- year (int, optional) – Year when data was collected
- lumi (float, optional) – Aggregate luminosity shown. Should require
"data"
to beTrue
. - lumi_format (string, optional, default is “{0}”) – Format string for luminosity number, e.g. “{0:.1f}”
- com (float, optional, default is 13, but can be changed to 7/8/13.6/14 to fit different requirements) –
- llabel (string, optional) – String to manually set left-hand label text. Will overwrite “data” and “label” kwargs.
- rlabel (string, optional) – String to manually set right-hand label text.
- fontname (string, optional) – Name of font to be used.
- fontsize (string, optional) – Defines size of “secondary label”. Experiment label is 1.3x larger.
- exp_weight (string, optional) – Set fontweight of <exp> label. Default “bold”.
- italic ((bool, bool), optional) – Tuple of bools to switch which label is italicized
- pad (float, optional) – Additional padding from axes border in units of axes fraction size.
- exp (string) – Experiment name, unavailable in public
<experiment>text()
.
Returns: ax – A matplotlib Axes object
Return type: matplotlib.axes.Axes
-
mplhep.atlas.
text
(text='', **kwargs)[source][source]¶ Add typical LHC experiment primary label to the axes. :param text: Secondary experiment label, typically not-bold and smaller
font-size. For example “Simulation” or “Preliminary”Parameters: - loc (int, optional) – Label position: - 0 : Above axes, left aligned - 1 : Top left corner - 2 : Top left corner, multiline - 3 : Split EXP above axes, rest of label in top left corner”
- ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched)
- fontname (string, optional) – Name of font to be used.
- fontsize (string, optional) – Defines size of “secondary label”. Experiment label is 1.3x larger.
- exp_weight (string, optional) – Set fontweight of <exp> label. Default “bold”.
- italic ((bool, bool), optional) – Tuple of bools to switch which label is italicized
- pad (float, optional) – Additional padding from axes border in units of axes fraction size.
Returns: ax – A matplotlib Axes <https://matplotlib.org/3.1.1/api/axes_api.html> object
Return type: matplotlib.axes.Axes
-
mplhep.atlas.
label
(label=None, **kwargs)[source][source]¶ A convenience wrapper combining
<exp>.text
andlumitext
providing for the most common use cases. :param loc: Label position ofexp_text
label:- 0 : Above axes, left aligned
- 1 : Top left corner
- 2 : Top left corner, multiline
- 3 : Split EXP above axes, rest of label in top left corner”
- 4 : (1) Top left corner, but align “rlabel” underneath
Parameters: - ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched)
- data (bool, optional) – Prevents prepending “Simulation” to experiment label. Default
False
. - label (str, optional) – Text to append after <exp> (Simulation) <label>. Typically “Preliminary” “Supplementary”, “Private Work” or “Work in Progress”
- year (int, optional) – Year when data was collected
- lumi (float, optional) – Aggregate luminosity shown. Should require
"data"
to beTrue
. - lumi_format (string, optional, default is “{0}”) – Format string for luminosity number, e.g. “{0:.1f}”
- com (float, optional, default is 13, but can be changed to 7/8/13.6/14 to fit different requirements) –
- llabel (string, optional) – String to manually set left-hand label text. Will overwrite “data” and “label” kwargs.
- rlabel (string, optional) – String to manually set right-hand label text.
- fontname (string, optional) – Name of font to be used.
- fontsize (string, optional) – Defines size of “secondary label”. Experiment label is 1.3x larger.
- exp_weight (string, optional) – Set fontweight of <exp> label. Default “bold”.
- italic ((bool, bool), optional) – Tuple of bools to switch which label is italicized
- pad (float, optional) – Additional padding from axes border in units of axes fraction size.
- exp (string) – Experiment name, unavailable in public
<experiment>text()
.
Returns: ax – A matplotlib Axes object
Return type: matplotlib.axes.Axes
-
mplhep.lhcb.
text
(text='', **kwargs)[source][source]¶ Add typical LHC experiment primary label to the axes. :param text: Secondary experiment label, typically not-bold and smaller
font-size. For example “Simulation” or “Preliminary”Parameters: - loc (int, optional) – Label position: - 0 : Above axes, left aligned - 1 : Top left corner - 2 : Top left corner, multiline - 3 : Split EXP above axes, rest of label in top left corner”
- ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched)
- fontname (string, optional) – Name of font to be used.
- fontsize (string, optional) – Defines size of “secondary label”. Experiment label is 1.3x larger.
- exp_weight (string, optional) – Set fontweight of <exp> label. Default “bold”.
- italic ((bool, bool), optional) – Tuple of bools to switch which label is italicized
- pad (float, optional) – Additional padding from axes border in units of axes fraction size.
Returns: ax – A matplotlib Axes <https://matplotlib.org/3.1.1/api/axes_api.html> object
Return type: matplotlib.axes.Axes
-
mplhep.lhcb.
label
(label=None, **kwargs)[source][source]¶ A convenience wrapper combining
<exp>.text
andlumitext
providing for the most common use cases. :param loc: Label position ofexp_text
label:- 0 : Above axes, left aligned
- 1 : Top left corner
- 2 : Top left corner, multiline
- 3 : Split EXP above axes, rest of label in top left corner”
- 4 : (1) Top left corner, but align “rlabel” underneath
Parameters: - ax (matplotlib.axes.Axes, optional) – Axes object (if None, last one is fetched)
- data (bool, optional) – Prevents prepending “Simulation” to experiment label. Default
False
. - label (str, optional) – Text to append after <exp> (Simulation) <label>. Typically “Preliminary” “Supplementary”, “Private Work” or “Work in Progress”
- year (int, optional) – Year when data was collected
- lumi (float, optional) – Aggregate luminosity shown. Should require
"data"
to beTrue
. - lumi_format (string, optional, default is “{0}”) – Format string for luminosity number, e.g. “{0:.1f}”
- com (float, optional, default is 13, but can be changed to 7/8/13.6/14 to fit different requirements) –
- llabel (string, optional) – String to manually set left-hand label text. Will overwrite “data” and “label” kwargs.
- rlabel (string, optional) – String to manually set right-hand label text.
- fontname (string, optional) – Name of font to be used.
- fontsize (string, optional) – Defines size of “secondary label”. Experiment label is 1.3x larger.
- exp_weight (string, optional) – Set fontweight of <exp> label. Default “bold”.
- italic ((bool, bool), optional) – Tuple of bools to switch which label is italicized
- pad (float, optional) – Additional padding from axes border in units of axes fraction size.
- exp (string) – Experiment name, unavailable in public
<experiment>text()
.
Returns: ax – A matplotlib Axes object
Return type: matplotlib.axes.Axes
Axes helpers¶
Use all helpers together
-
mplhep.
mpl_magic
(ax=None, info=True)[source][source]¶ - Consolidate all ex-post style adjustments:
- ylow yscale_legend
or one by one.
-
mplhep.plot.
ylow
(ax=None, ylow=None)[source][source]¶ Set lower y limit to 0 if not data/errors go lower. Or set a specific value
Figure helpers¶
-
mplhep.
append_axes
(ax, size=0.1, pad=0.1, position='right', extend=False)[source][source]¶ Append a side ax to the current figure and return it. Figure is automatically extended along the direction of the added axes to accommodate it. Unfortunately can not be reliably chained.
-
mplhep.
box_aspect
(ax, aspect=1)[source][source]¶ Adjust figure size to axes size in inches Parameters: aspect: float, optional aspect ratio
Legend helpers¶
Styles¶
To be included, when I figure out how to sphinx dictionaries in.