Plotting

2D plotting (histograms as lines, points, or bands)

2D plotting, i.e. plotting of 1D histograms. A single histogram stack as well as any number of individual histograms visualised as curves, points, bands can be shown. Any number of panels (called “pads” in ROOT) can be included in a single figure.

The function for making a 2D plot is make_figure.

A special convenience function for plotting a breakdown of the uncertainties of a single histogram called make_uncertainty_breakdown is also provided.

heppy.make_figure(panels, title='', figsize=(8, 5), write='', xlims=None, xmax=None, legend_outside=False)
Parameters:
  • panels (heppy.panel or list of heppy.panel) – panel(s) to visualise in the plot
  • title (str) – plot title
  • write (str) – may be changed to a filename, which will result in the figure being rendered and saved at the given location
  • legend_outside (bool) – option to move the legend next to the plot panels. It also changes the legend style to try to make it look better next to the plot: no box, text wrapped at 30 characters (not tested with LaTeX rendering — proceed with caution), smaller text (fontsize=’small’)
  • xlims (tuple of float, or None) – can be used to manually set lower and upper x-axis limits, e.g. xlims=(0.0, 2.0)
Returns:

tuple of the created plt.figure object and plt.axes objects. These can be assigned to variables by the user to allow further manipulations of the plot (style, contents, etc.)
class heppy.panel(title='', height=1.0, xlabel='', ylabel='', logx=False, logy=False, stack=None, curves=[], bands=[], points=[], pointshift=0.0, scatters=[], ylims=None, nolegend=False, legend_title=None, legend_loc=None, unbinned=[])

A panel holds histograms and other information that describe a panel of a plot

Parameters:
  • title (str) – title of the panel
  • height (float) – relative height of the panel with respect to any other panels in a plot
  • xlabel (str) – x-axis label
  • ylabel (str) – y-axis label
  • logx (bool) – plot x-axis on a logarithmic scale?
  • logy (bool) – plot y-axis on a logarithmic scale?
  • stack (heppy.histostack, or None) – histogram stack to plot
  • curves (list of heppy.histogram1d) – histograms to plot as curves
  • bands (list of heppy.histogram1d) – histograms to plot as (uncertainty) bands
  • points (list of heppy.histogram1d) – histograms to plot as points located at the centre of each of their bins
  • pointshift (float) – distance to shift points by horizontally to avoid overlap and improve readability. This functionality is poorly tested and may be broken
  • scatters (list of heppy.histogram1d) – this is a bit of an oddball. You can use it to plot 2D scatters that aren’t really histograms. The x-values are lower bin edges (the uppermost binedge is not used for anything) while the y-values are the areas.
  • ylims (tuple of float, or None) – can be used to manually set lower and upper y-axis limits, e.g. ylims=(0.0, 2.0)
  • legend_title (str) – legend title
  • legend_loc (whatever Matplotlib accepts for the loc keyword arg of legend) – legend title
  • unbinned (list of tuples, each tuple has two np.arrays and a plot attribute dict) – unbinned curves, given as tuple of x and y values (for matplotlib.pyplot.plot)
heppy.make_uncertainty_breakdown(histogram, separator='__', ylims=None, xlabel='', **kwargs)

@histogram: heppy.histogram object for which the uncertainty breakdown figure will be made @separator: string that separates high/low (up/down, …) indictator from the rest of the uncertainty name, e.g. “jet_energy_scale__1up” and “jet_energy_scale__1down” uses the separator “__” @ylims: may be set to a tuple/list of lower and upper y-axis limits, e.g. ylims=(0.0, 2.0) @**kwargs: get passed on to make_figure()

3D plotting (histogram as heatmap)

3D plotting, i.e. plotting of 2D histograms. Only a single histogram can be put into each plot. The histogram contents can be printed onto the histogram in a nicely formatted way for better readability.

heppy.make_heatmap(histogram, areas=False, title='', figsize=(8, 5), colorbar=True, text_format=<function TextFormatter.brief>, text_precision=3, text_autocolor=True, black_text_below=None, monowidth=False, write='', xmax=None, **kwargs)

Make a heatmap plot of a two-dimensional histogram

Parameters:
  • histogram (heppy.histogram2d) – two-dimensional histogram to visualise
  • title (str) – plot title
  • figsize (tuple of float) – figure size
  • colorbar (bool) – show color bar or not
  • text_format (str, function or None) – string template or function returning the text to be printed inside each bin. The following format keys (if string) or keyword arguments (if function) will be provided: {nominal}, {uncert_up} and {uncert_down} for total uncertainty, {stat_up} and {stat_down} for statistical uncertainty, {syst_up} and {syst_down} for systematic uncertainty. All uncertainties are given as non-negative numbers. The class heppy.TextFormatter provides a set of useful and somewhat adaptable predefined formatter functions.
  • monowidth (bool) – if True, all bins are shown as equally wide/high, with the bin edges written in the label.
  • write (str) – may be changed to a filename, which will result in the figure being rendered and saved to disk
  • **kwargs –

    keyword arguments that get passed on to plt.hist2d

The following keys in histogram.plot_attributes can be used to set axis labels:

  • "xlabel" – x-axis label
  • "ylabel" – y-axis label
class heppy.TextFormatter

Predefined functions to format bin content text printed on heatmap. The user can alternatively write their own such functions.

Contents will be printed with a precision of (up to) three significant digits. If you want to set a different precision, you can create your own adapted formatting function as the following example illustrates:

import functools
# set the number of significant digits (e.g. to 4)
formatter = functools.partial(TextFormatter.nominal, significants=4)
# or set the fixed absolute precision (e.g. to 3 digits after the decimal point)
formatter = functools.partial(TextFormatter.nominal, fixedprec=3)
# then use as: heppy.make_heatmap(..., text_format=formatter, ...)

Here significants represents the maximum number of significant digits considered (default: 3), while fixedprec represents the fixed absolute precision considered, e.g. 1 for a precision of 0.1 or -1 for a precision of 10 (default: None). If fixedprec is given, significants is ignored.

Hint: when writing a custom formatting function, any unnecessary keyword arguments can be absorbed into a **kwargs catch-all parameter to keep the function signature shorter and tidier.

static nominal(significants=3, fixedprec=None, nominal=None, **ignore)

Returns LaTeX string of nominal value.

static brief(significants=3, fixedprec=None, nominal=None, uncert_up=None, uncert_down=None, **ignore)

Returns LaTeX string of nominal value and total uncertainty.

The format is \(\mathrm{nominal} \pm \sigma\), where \(\sigma\) is the uncertainty from the uncorrelated variations and the correlated variations. Asymmetric uncertainties are supported and will be shown as \(^{\sigma^{\mathrm{up}}}_{\sigma^{\mathrm{down}}}\).

static statsyst(significants=3, fixedprec=None, nominal=None, stat_up=None, stat_down=None, syst_up=None, syst_down=None, **ignore)

Returns LaTeX string of nominal value and statistical and systematic uncertainty.

The format is \(\mathrm{nominal} \pm \sigma_{\mathrm{stat}} \pm \sigma_{\mathrm{syst}}\), where \(\sigma_{\mathrm{stat}}\) is the uncertainty from the uncorrelated variations and \(\sigma_{\mathrm{syst}}\) is the uncertainty from the correlated variations. Asymmetric uncertainties are supported and will be shown as \(^{\sigma_{\mathrm{syst}}^{\mathrm{up}}}_{\sigma_{\mathrm{syst}}^{\mathrm{down}}}\) etc.