Heatmap (3D plot)

heppy.make_heatmap(histogram, areas=False, title='', figsize=(8, 5), text_format=<function TextFormatter.brief>, text_precision=3, text_autocolor=True, 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
  • 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 labels:

  • "title" – plot title
  • "xlabel" – x-axis label
  • "ylabel" – y-axis label
  • "zlabel" – z-axis (colour palette) 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.