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). Here low and high are given in absolute terms, not relative to w. Default is None. If w2 has integer values (likely to be data) poisson interval is calculated, otherwise the resulting error is symmetric sqrt(w2). Specifying poisson or sqrt 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:

  • xerr (bool or float, optional) – Size of xerr if histtype == 'errorbar'. If True, 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]
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

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 and lumitext providing for the most common use cases. :param loc: Label position of exp_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 be True.
  • 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 and lumitext providing for the most common use cases. :param loc: Label position of exp_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 be True.
  • 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 and lumitext providing for the most common use cases. :param loc: Label position of exp_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 be True.
  • 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

mplhep.plot.yscale_legend(ax=None)[source][source]

Automatically scale y-axis up to fit in legend()

mplhep.plot.yscale_text(ax=None)[source][source]

Automatically scale y-axis up to fit AnchoredText

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

mplhep.make_square_add_cbar(ax, size=0.4, pad=0.1)[source][source]

Make input axes square and return an appended axes to the right for a colorbar. Both axes resize together to fit figure automatically. Works with tight_layout().

mplhep.rescale_to_axessize(ax, w, h)[source][source]

Adjust figure size to axes size in inches Parameters: w, h: width, height in inches

Legend helpers

mplhep.sort_legend()[source][source]

ax : axes with legend labels in it order : Ordered dict with renames or array with order

Styles

To be included, when I figure out how to sphinx dictionaries in.