atlas_mpl_style Module

atlas_mpl_style.ratio_axes(extra_axes=None)

Splits axes for ratio plots.

Parameters:

  • extra_axes (int, optional) – Number of additional axes. If not given, defaults to one.

  • square (bool, optional) – Whether the plot should be square or tall. Defaults to True (square)

Returns:

  • fig (figure)

  • main_ax (axes)

  • ratio_ax (axes or list of axes) – Returns list if extra_axes is passed

atlas_mpl_style.set_color_cycle(pal=None, n=4)

Sets a different color cycle.

The ATLAS palette includes the standard green and yellow.

Parameters:

  • pal ({'ATLAS', 'Paper', 'Oceanic', 'MPL', "HDBS", "HH", None}) –

    The palette to use. None resets to default palette. The ATLAS palette is suitable for histograms, not lines.

    ’MPL’ (alias ‘Tab’) provides the default matplotlib palette.

  • n (int, optional) – Number of lines or histograms.

atlas_mpl_style.use_atlas_style(atlasLabel='ATLAS', fancyLegend=False, usetex=False)

Setup ATLAS style.

Parameters:

  • atlasLabel (str, optional) – Replace ATLAS with a custom label

  • fancyLegend (bool, optional) – Use matplotlib’s fancy legend frame (defaults to False)

  • usetex (bool, optional) – Use LaTeX installation to set text (defaults to False) If no LaTeX installation is found, this package will fallback to usetex=False. This is on a best-effort basis, since the detected LaTeX installation may be incomplete.

atlas_mpl_style.plot Module

class atlas_mpl_style.plot.Background(label, hist, stat_errs=None, syst_errs=None, color=None)

Histogram and errors corresponding to a single background

exception atlas_mpl_style.plot.BinningMismatchError(msg)

Error due to histogram binning mismatch

exception atlas_mpl_style.plot.DimensionError(msg)

Error due to incorrect / unsupported histogram dimension

exception atlas_mpl_style.plot.ViolatesPlottableHistogramError(msg)

Error due to histogram object violating the PlottableHistogram protocol

atlas_mpl_style.plot.draw_atlas_label(x, y, ax=None, status='int', simulation=False, energy=None, lumi=None, desc=None, lumi_lt=False, *args, **kwargs)

Draw ATLAS label.

Additional parameters are passed through to ax.text.

Parameters:

  • x (float) – x position (top left)

  • y (float) – y position (top left)

  • ax (mpl.axes.Axes, optional) – Axes to draw label in

  • status ([ ‘int’ | ‘wip’ | ‘prelim’ | ‘final’ | ‘opendata’ ], optional) – Approval status

  • simulation (bool (optional, default False)) – Does the plot show only MC simulation results

  • energy (str, optional) – Centre of mass energy, including units

  • lumi (float or str, optional) – Integrated luminosity in /fb. If str, the units should be included.

  • lumi_lt (bool, optional) – True if only a subset of data was processed

  • desc (str, optional) – Additional description

atlas_mpl_style.plot.draw_legend(*args, ax=None, **kwargs)

Add legend to axes with data first, and uncertainties last.

Parameters:

  • ax (mpl.axes.Axes, optional) – Axes to draw legend on (defaults to current axes)

  • *args – Passed to ax.legend

  • **kwargs – Passed to ax.legend

atlas_mpl_style.plot.draw_tag(text, ax=None)

Draw tag just outside plot region

Parameters:

  • text (str)

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

atlas_mpl_style.plot.plot_1d(label, bins, hist, stat_errs=None, color=None, attach_bands=False, ax=None, **kwargs)

Plot single 1D histogram

NB: atlas_mpl_style.uhi.plot_1d() provides a version of this function that accepts a PlottableHistogram.

Parameters:

  • label (str) – Label for legend

  • bins (array_like) – Bin edges

  • hist (array_like) – Bin contents

  • stat_errs (array_like, optional) – Statistical errors

  • color (color, optional) – Line color

  • attach_bands (boolean, optional) – Attach bands to line in legend. Defaults to False.

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

  • **kwargs – Extra parameters passed to plt.hist

atlas_mpl_style.plot.plot_2d(xbins, ybins, hist, ax=None, pad=0.05, **kwargs)

Plot 2D histogram

NB: atlas_mpl_style.uhi.plot_2d() provides a version of this function that accepts a PlottableHistogram.

Parameters:

  • xbins (array_like) – x bin edges

  • bins (array_like) – y bin edges

  • hist (array_like) – Bin contents

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

  • pad (float, optional) – Padding for colorbar in inches (defaults to 0.05)

  • **kwargs – Extra parameters passed to pcolormesh

Returns:

  • mesh (QuadMesh)

  • cbar (mpl.colorbar.Colorbar)

atlas_mpl_style.plot.plot_backgrounds(backgrounds, bins=None, *, total_err=None, empty_stat_legend=False, ax=None)

Plot stacked backgrounds

Parameters:

  • backgrounds ([Background]) – List of backgrounds to be plotted, in order (bottom to top)

  • bins (array_like, optional) – Bin edges. To preserve backward compatibility, backgrounds and bins may be exchanged.

  • total_err (array_like, optional) – Total uncertainty. If given, overrides per-background systematics. This is useful for showing post-fit uncertainties.

  • empty_stat_legend (boolean, optional) – Add stat error band to legend even if empty. Defaults to False.

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

Returns:

  • total_hist (array_like) – Total background histogram

  • total_err (array_like) – Total error on background histogram

atlas_mpl_style.plot.plot_band(bins, low, high, label=None, ax=None, **kwargs)

Draw a shaded band between high and low

Use this for drawing error bands

Parameters:

  • bins (array_like) – Bin edges

  • low (array_like) – Bin contents defining lower bound

  • high (array_like) – Bin contents defining upper bound

  • label (str, optional) – Label for legend. If label matches a line, the band will be attached to that line if draw_legend is used.

  • ax (mpl.axes.Axes, optional) – Axes to draw band on (defaults to current axes)

  • **kwargs – Keyword arguments passed to fill_between

atlas_mpl_style.plot.plot_cutflow(labels, hist, ax=None, text=True, textcolor='w', horizontal=True, **kwargs)

Plot cutflow from PlottableHistogram

Parameters:

  • labels ([str]) – Cutflow labels

  • hist (PlottableHistogram) – Cutflow histogram

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

  • text (bool, optional) – Whether to label bars (default: True)

  • textcolor (str, optional) – Text color

  • horizontal (bool, optional) – Whether to draw horizontal bars (default: True)

  • **kwargs – Extra parameters passed to bar or barh

atlas_mpl_style.plot.plot_data(bins, hist, stat_errs=None, color='k', label='Data', ax=None)

Plot data

NB: atlas_mpl_style.uhi.plot_data() provides a version of this function that accepts a PlottableHistogram.

Parameters:

  • label (str, optional) – Label for legend (default: “Data”)

  • bins (array_like) – Bin edges

  • hist (array_like) – Bin contents

  • stat_errs (array_like, optional) – Statistical errors

  • color (color, optional) – Point color, defaults to black

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

Returns:

  • hist (array_like) – Data histogram

  • stat_errs (array_like) – Statistical errors

atlas_mpl_style.plot.plot_limit(expected_label, x, expected, minus_one_sigma=None, plus_one_sigma=None, minus_two_sigma=None, plus_two_sigma=None, observed_label=None, observed=None, color=None, ax=None)

Plot a limit

Parameters:

  • expected_label (str) – Label for expected limit (for legend)

  • x (array_like) – x values

  • expected (array_like) – Expected limit

  • minus_one_sigma (array_like, optional) – Lower edge of one sigma band

  • plus_one_sigma (array_like, optional) – Upper edge of one sigma band

  • minus_two_sigma (array_like, optional) – Lower edge of two sigma band

  • plus_two_sigma (array_like, optional) – Upper edge of two sigma band

  • observed_label (str, optional) – Label for observed limit

  • observed (array_like, optional) – Observed limit

  • color (color, optional) – Line color (if multiple limits are being drawn)

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

atlas_mpl_style.plot.plot_ratio(bins, data, data_errs, bkg, bkg_errs, ratio_ax, max_ratio=None, plottype='diff', offscale_errs=False)

Plot ratio plot

NB: atlas_mpl_style.uhi.plot_ratio() provides a version of this function that accepts ``PlottableHistogram``s.

Parameters:

  • bins (array_like) – Bin edges

  • data (array_like) – Data histogram bin contents

  • data_errs (array_like) – Statistical errors on data

  • bkg (array_like) – Total background histogram bin contents

  • bkg_errs (array_like) – Total errors on total background

  • ratio_ax (mpl.axes.Axes) – Ratio axes (produced using atlas_mpl_style.ratio_axes())

  • max_ratio (float, optional) – Maximum ratio (defaults to 0.25 for “diff”, 1.25 for “raw”, 3.5 for “significances”).

  • plottype ({"diff", "raw", "significances"}) –

    Type of ratio to plot.
    ”diff” : (data - bkg) / bkg
    ”raw” : data / bkg
    ”significances” : Significances (using atlas_mpl_style.utils.significance())

  • offscale_err (boolean) – Draw error bars on off-scale points

atlas_mpl_style.plot.plot_signal(label, bins, hist, stat_errs=None, syst_errs=None, color=None, attach_bands=False, ax=None)

Plot signal histogram

NB: atlas_mpl_style.uhi.plot_signal() provides a version of this function that accepts a PlottableHistogram.

Parameters:

  • label (str) – Label for legend

  • bins (array_like) – Bin edges

  • hist (array_like) – Bin contents

  • stat_errs (array_like) – Statistical errors

  • syst_errs (array_like) – Systematic errors

  • color (color) – Line color

  • attach_bands (boolean, optional) – Attach bands to line in legend. Defaults to False.

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

atlas_mpl_style.plot.register_band(label, artist, ax=None)

Register a manually draw (e.g. with fill_between) error band.

Parameters:

  • label (str) – Label of line to attach band to.

  • artist (mpl.artist.Artist) – Band artist, e.g. PolyCollection returned by fill_between.

  • ax (mpl.axes.Axes, optional) – Axes to register band in (defaults to current axes).

atlas_mpl_style.plot.set_xlabel(label, ax=None, *args, **kwargs)

Set x label in ATLAS style (right aligned). If ratio_axes was used, the label will be set on the lowest ratio axes.

Additional parameters are passed through to ax.set_xlabel.

Parameters:

  • label (str) – Label (LaTeX permitted)

  • ax (mpl.axes.Axes, optional) – Axes to set x label on

atlas_mpl_style.plot.set_ylabel(label, ax=None, *args, **kwargs)

Set y label in ATLAS style (top aligned).

Additional parameters are passed through to ax.set_ylabel.

Parameters:

  • label (str) – Label (LaTeX permitted)

  • ax (mpl.axes.Axes, optional) – Axes to set y label on

atlas_mpl_style.plot.set_zlabel(label, cbar=None, ax=None, **kwargs)

Set z label in ATLAS style (top aligned)

The colorbar to add the label to is required unless plot_2d was used.

Parameters:

  • label (str) – Label (LaTeX permitted)

  • cbar (mpl.colorbar.Colorbar, optional) – Colorbar to set label on. Not required if plot_2d was used.

  • ax (mpl.axes.Axes, optional) – If plot_2d was used, the axes can optionally be provided here.

atlas_mpl_style.stats Module

exception atlas_mpl_style.stats.IncorrectAxesError(msg)

Error due to passing incorrect axes to draw_pull_impact_legend

atlas_mpl_style.stats.draw_pull_impact_legend(*args, ax=None, **kwargs)

Add legend to a pull / impact plot.

Parameters:

  • ax (mpl.axes.Axes, optional) – Pull axes

  • **kwargs – Passed to ax.legend

atlas_mpl_style.stats.make_impact_figure(num_parameters)

Create a new figure for a pull / impact plot.

Parameters:

num_parameters (Integer) – Number of parameters on this plot

Returns:

fig – Created figure

Return type:

Figure

atlas_mpl_style.stats.plot_impacts(data, draw_prefit=False, up_color='paper:blue', down_color='paper:red', ax=None)

Plot impacts from a Pandas dataframe (data).

The dataframe must have the following columns. The prefit columns are not required if draw_prefix == False.

name

Parameter name

impact_prefit_up

Impact on POI from fit with parameter fixed to +1σ (using prefit σ)

impact_prefit_down

Impact on POI from fit with parameter fixed to -1σ (using prefit σ)

impact_postfit_up

Impact on POI from fit with parameter fixed to +1σ (using postfit σ)

impact_postfit_down

Impact on POI from fit with parameter fixed to -1σ (using postfit σ)
Parameters:

  • data (pd.DataFrame) – Pandas dataframe containing impacts

  • draw_prefit (Boolean, optional) – Whether to draw the prefit bands

  • up_color (Color specification) – Color to use for upper band (postfit band will be at 50% opacity)

  • up_color – Color to use for lower band (postfit band will be at 50% opacity)

  • ax (mpl.axes.Axes, optional) – Axes to pulls were drawn on (defaults to current axes). Impact axes will be a twin of these.

Returns:

ax – The axes impacts were drawn on

Return type:

mpl.axes.Axes

atlas_mpl_style.stats.plot_pulls(data, ax=None, **kwargs)

Plot pulls from a Pandas dataframe (data).

The dataframe must have at least the following columns:

name

Parameter name

value

Post nominal fit central value of parameter

err_high

Post nominal fit error (high side) on parameter

err_low

Post nominal fit error (low side) on parameter.
Parameters:

  • data (pd.DataFrame) – Pandas dataframe containing pulls

  • ax (mpl.axes.Axes, optional) – Axes to draw pulls on (defaults to current axes)

  • **kwargs – Keyword arguments passed to errorbar

Returns:

  • ax (mpl.axes.Axes) – The axes pulls were drawn on

  • pull_plot (mpl.container.ErrorbarContainer) – The return value of errorbar

atlas_mpl_style.stats.sort_impacts(data)

Sort an impact (and pull) dataframe in-place by descending postfit impacts.

The frame must have at least the following columns:

name

Parameter name

impact_postfit_up

Impact on POI from fit with parameter fixed to +1σ (using postfit σ)

impact_postfit_down

Impact on POI from fit with parameter fixed to -1σ (using postfit σ)
Parameters:

data (pd.DataFrame) – Pandas dataframe containing impacts

atlas_mpl_style.uhi Module

This module contains versions of the histogram plotting functions that take PlottableHistograms

These are in a separate module to preserve backward compatibility since the array versions of these functions take the array of bins before the histogram.

atlas_mpl_style.plot.Background can be constructed using a PlottableHistogram and therefore there is no atlas_mpl_style.uhi.plot_backgrounds function.

exception atlas_mpl_style.uhi.LabeledBinsError(msg)

Labeled bins when edges expected (or vice versa)

atlas_mpl_style.uhi.plot_1d(hist, label, ignore_variances=False, stat_err=True, color=None, attach_bands=False, ax=None, **kwargs)

Plot single 1D histogram from PlottableHistogram

Parameters:

  • hist (PlottableHistogram) – Histogram

  • label (str) – Label for legend

  • ignore_variances (bool) – Ignore variances and substitute hist. Defaults to False.

  • stat_err (bool) – Draw statistical errors. Defaults to True.

  • color (color, optional) – Line color

  • attach_bands (boolean, optional) – Attach bands to line in legend. Defaults to False.

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

  • **kwargs – Extra parameters passed to plt.hist

atlas_mpl_style.uhi.plot_2d(hist, ax=None, pad=0.05, **kwargs)

Plot 2D histogram from PlottableHistogram

Parameters:

  • hist (PlottableHistogram) – Histogram

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

  • pad (float, optional) – Padding for colorbar in inches (defaults to 0.05)

  • **kwargs – Extra parameters passed to pcolormesh

Returns:

  • mesh (QuadMesh)

  • cbar (mpl.colorbar.Colorbar)

atlas_mpl_style.uhi.plot_cutflow(hist, ax=None, text=True, textcolor='w', horizontal=True, **kwargs)

Plot cutflow from PlottableHistogram

Parameters:

  • hist (PlottableHistogram) – Cutflow histogram

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

  • text (bool, optional) – Whether to label bars (default: True)

  • textcolor (str, optional) – Text color

  • horizontal (bool, optional) – Whether to draw horizontal bars (default: True)

  • **kwargs – Extra parameters passed to bar or barh

atlas_mpl_style.uhi.plot_data(hist, ignore_variances=False, color='k', label='Data', ax=None)

Plot data from PlottableHistogram

Parameters:

  • label (str, optional) – Label for legend (default: “Data”)

  • hist (PlottableHistogram) – Histogram

  • ignore_variances (bool) – Ignore variances and substitute hist. Defaults to False.

  • color (color, optional) – Point color, defaults to black

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

Returns:

  • hist (array_like) – Data histogram

  • stat_errs (array_like) – Statistical errors

atlas_mpl_style.uhi.plot_ratio(data, total_bkg, ratio_ax, max_ratio=None, plottype='diff')

Plot ratio plot from PlottableHistogram

Parameters:

  • data (PlottableHistogram) – Data histogram

  • total_bkg ((array_like, array_like)) – Tuple returned from atlas_mpl_style.plot.plot_backgrounds()

  • ratio_ax (mpl.axes.Axes) – Ratio axes (produced using atlas_mpl_style.ratio_axes())

  • max_ratio (float, optional) – Maximum ratio (defaults to 0.2 for “diff”, 1.2 for “raw”, 3 for “significances”)

  • plottype ({"diff", "raw", "significances"}) –

    Type of ratio to plot.
    ”diff” : (data - bkg) / bkg
    ”raw” : data / bkg
    ”significances” : Significances (from ampl.utils.significance())

atlas_mpl_style.uhi.plot_signal(hist, label, ignore_variances=False, syst_errs=None, color=None, attach_bands=False, ax=None)

Plot signal histogram from PlottableHistogram

Parameters:

  • hist (PlottableHistogram) – Histogram

  • label (str) – Label for legend

  • ignore_variances (bool) – Ignore variances and substitute hist. Defaults to False.

  • syst_errs (array_like or PlottableHistogram, optional) – Systematic errors

  • color (color) – Line color

  • attach_bands (boolean, optional) – Attach bands to line in legend. Defaults to False.

  • ax (mpl.axes.Axes, optional) – Axes to draw on (defaults to current axes)

atlas_mpl_style.utils Module

atlas_mpl_style.utils.significance(data, data_errs, bkg, bkg_errs)

Calculates significance in each bin

Uses the significance definition in https://cds.cern.ch/record/2643488

Parameters:

  • data (array_like)

  • data_errs (array_like) – Errors / uncertainties on data

  • bkg (array_like) – Total background prediction

  • bkg_errs (array_like) – Errors / uncertainties on bkg