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='', xmax=None, legend_outside=False)¶ Parameters: - panels (
heppy.panel
orlist
ofheppy.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’)
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.)
- panels (
-
class
heppy.
panel
(title='', height=1.0, xlabel='', ylabel='', logx=False, logy=False, stack=None, curves=[], bands=[], points=[], pointshift=0.0, ylims=None, nolegend=False, legend_title=None)¶ 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
- 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
-
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), 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
offloat
) – figure size - text_format (
str
,function
orNone
) – 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 classheppy.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
- histogram (
-
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), whilefixedprec
represents the fixed absolute precision considered, e.g.1
for a precision of 0.1 or-1
for a precision of 10 (default:None
). Iffixedprec
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.
-
static