API Reference#

This section covers all the main interfaces and objects used in atlasplots.

atlasplots.api module#

atlasplots.api#

This module implements the ATLAS Plots API.

copyright:

  1. 2020-2021 Joey Carter.

license:

MIT, see LICENSE for more details.

atlasplots.api.atlas_label(x=None, y=None, text='', loc='', size=None, font=None, align=None, color=None, alpha=None, angle=None)#

Draws the “official” ATLAS label.

Guidelines from PubCom:

An ATLAS label must be present on plots which have been approved by ATLAS:

  • ATLAS: means the plot has been submitted for publication or is in the associated approved auxiliary material (i.e. an ATLAS paper, or a pre-datataking publication like the CSC notes).

  • ATLAS Preliminary: means the plot has been approved by ATLAS but has not appeared in a refereed publication. This is used in particular for CONF and PUB notes.

  • ATLAS Work In Progress: used only in student talks at national meetings where the student is presenting what is largely her own work. This should not be used for internal plots inside ATLAS.

  • ATLAS Internal: for plots shown in internal ATLAS talks (including approval talks) or included in draft documents circulated to ATLAS.

Parameters:

  • x (float, optional) –

    The x- and y-coordinates of the ATLAS label in NDC units [0, 1].

    This x-coordinate is left-aligned and the y-coordinate is top-aligned unless the align argument is given.

  • y (float, optional) –

    The x- and y-coordinates of the ATLAS label in NDC units [0, 1].

    This x-coordinate is left-aligned and the y-coordinate is top-aligned unless the align argument is given.

  • text (str, optional) – Additional text, e.g. “Internal”, “Preliminary”, etc. ROOT TLatex syntax is supported.

  • loc (str, optional) –

    The location of the ATLAS label.

    The strings ‘upper left’, ‘upper right’, ‘lower left’, ‘lower right’ place the label at the corresponding corner of the axes/figure. This option is overridden if the x and y arguments are provided.

    The default location is ‘upper left’.

  • size (float, optional) – Text size.

  • font (int, optional) – ROOT font code.

  • align (int, optional) – ROOT text-alignment code.

  • color (int, optional) – ROOT text-color code.

  • alpha (float, optional) –

    Text alpha.

    Not recommended for official ATLAS labels!

  • angle (float, optional) –

    Text angle in degrees.

    Not recommended for official ATLAS labels!

Returns:

The TLatex object for this label.

Return type:

ROOT.TLatex

atlasplots.api.figure(name='', title='', figsize=None)#

Create a new figure.

Parameters:

  • name (str, optional) – Figure (canvas) name.

  • title (str, optional) – Figure (canvas) title.

  • figsize ((float, float), optional) –

    Figure (canvas) dimension (width, height) in pixels. The default

    dimensions are (800, 600).

Returns:

fig – The figure.

Return type:

Figure

atlasplots.api.ratio_plot(hspace=0, **fig_kw)#

An opinionated method to produce a ratio plot, with a main panel to show two or more datasets, and a lower panel to show their ratios.

These settings are optimized for a 800 x 800 px canvas.

Parameters:

  • hspace (float) – Space between the main panel and ratio panel.

  • **fig_kw – All additional keyword arguments are passed to the api.figure() call.

Returns:

  • fig (Figure) – The figure.

  • ax (Array of Axes) – The axes. The first set of axes should be the main panel, and each subsequent set of axes should be the ratio panels.

atlasplots.api.set_atlas_style(tsize=None)#

Sets the global ROOT plot style to the ATLAS Style.

Parameters:

tsize (float, optional) – Text size in pixels. The default is None, in which case it will use the default text size defined in AtlasStyle().

atlasplots.api.subplots(nrows=1, ncols=1, width_ratios=None, height_ratios=None, **fig_kw)#

Create a figure and a set of subplots.

Parameters:

  • nrows (int, default: 1) – Number of rows/columns of the subplot grid.

  • ncols (int, default: 1) – Number of rows/columns of the subplot grid.

  • width_ratios (array-like of length ncols, optional) – Defines the relative widths of the columns. Each column gets a relative width of width_ratios[i] / sum(width_ratios). If not given, all columns will have the same width.

  • height_ratios (array-like of length nrows, optional) – Defines the relative heights of the rows. Each column gets a relative height of height_ratios[i] / sum(height_ratios). If not given, all rows will have the same height.

  • **fig_kw – All additional keyword arguments are passed to the api.figure() call.

Returns:

  • fig (Figure) – The figure.

  • ax (Axes or array of Axes) – ax can be either a single Axes object or an array of Axes objects if more than one subplot was created.

    Typical idioms for handling the return value are just like in matplotlib:

    # Using the variable ax for a single Axes
fig, ax = aplt.subplots()

# Using the variable axs for multiple Axes
fig, axs = aplt.subplots(2, 2)

# Using tuple unpacking for multiple Axes
fig, (ax1, ax2) = aplt.subplots(1, 2)
fig, ((ax1, ax2), (ax3, ax4)) = aplt.subplots(2, 2)

atlasplots.atlasstyle module#

atlasplots.atlasstyle#

Python implementation of the ATLAS PubCom style guide for plots in ROOT:

This implementation uses ROOT fonts with precision = 3, where text sizes are given in pixels. Using text sizes in pixels is useful for canvases with multiple TPads of different sizes, as the text size will not depend on the dimensions of the pad. The default font used by the ATLAS style is Arial (ROOT font 43).

For general instructions on formatting text in ROOT, refer to,

Examples

>>> import ROOT
>>> import atlasplots as aplt
>>> aplt.set_atlas_style()
>>> canv = ROOT.TCanvas("canv", "", 600, 600)
>>> ROOT.gPad.DrawFrame(0,0,1,1)
>>> aplt.atlas_label(text="Internal", loc='upper left');
copyright:

  1. 2020-2021 Joey Carter.

license:

MIT, see LICENSE for more details.

atlasplots.atlasstyle.atlas_style(tsize=29)#

Defines the “official” ATLAS plot style.

Parameters:

tsize (float, optional) – Text size in pixels (default: 29).

Returns:

The TStyle object defining the ATLAS Style.

Return type:

ROOT.TStyle

atlasplots.core module#

atlasplots.core#

This module contains the primary objects and methods that power ATLAS Plots.

copyright:

  1. 2020-2021 Joey Carter.

license:

MIT, see LICENSE for more details.

class atlasplots.core.Axes(pad_args=None, frame_args=None)#

Bases: object

A matplotlib-like Axes object powered by ROOT.

An Axes object is a wrapper around a ROOT TPad and a “frame” (which is an empty TH1F histogram object). Axes provides matplotlib-like syntax to change axis parameters, like set_xlim(), while still providing access to the underlying ROOT objects.

Parameters:

  • pad_args (tuple, optional) – Arguments to pass to the TPad constructor.

  • frame_args (tuple, optional) – Arguments to pass to the TH1F constructor to create the frame.

add_margins(left=0.0, right=0.0, bottom=0.0, top=0.0)#

Adds margins between the axes and the data within.

Parameters:

  • left (float, optional) – Margin sizes in NDC units [0, 1]. The default is 0.

  • right (float, optional) – Margin sizes in NDC units [0, 1]. The default is 0.

  • bottom (float, optional) – Margin sizes in NDC units [0, 1]. The default is 0.

  • top (float, optional) – Margin sizes in NDC units [0, 1]. The default is 0.

Notes

This function sets the margin size with respect to the current x- and y-axis limits, therefore multiple calls to add_margins() will incrementally add to the margin size. In most cases, add_margins() should only be called once per axes.

cd()#

Sets these axes as the current axes.

Equivalent to ax.pad.cd() (i.e. TPad::cd()).

Note that Axes.cd() does not need to be called before Axes.plot(); this is done automatically.

draw_arrows_outside_range(obj, arrowlength=0.12, arrowsize=0.015, buffer=0.01, option='|>', **kwargs)#

Draw arrows in place of data points outside the axis range.

This function plots upward-pointing arrows at the top of the axes when the data point is greater than the y-axis maximum and downard-pointing arrows at the bottom of the axes when the data point is less than the y-axis minimum.

Some care should be taken when drawing graphs with the “0” option in combination with this function, since this will draw the error bar even if a point is out of range, which may overlap with the arrow.

See the ROOT documentation for more information on drawing arrows:

Parameters:

  • obj (TH1 or TGraph) – Data object (histogram or graph) being plotted on these axes.

  • arrowsize (float, optional) – Size of the arrow head as in percentage of the pad height. The default is 0.015.

  • arrowlength (float, optional) – Arrow length as a fraction of the axes height. The default is 0.12.

  • buffer (float, optional) – Buffer space between the arrow head and the axes as in fraction of the axes height. The default is 0.01.

  • option (string, optional) – String indicating the arrow head style. The default is ‘|>', which draws an arrow in the form ---|>.

  • **kwargs (formatting options, optional) – kwargs are used to specify properties like arrow line and fill attributes. See plot() for usage.

property frame#

Returns the axes’ TH1F frame object.

get_xlabel()#

Get the xlabel text string.

get_xlim()#

Returns the frame’s x-axis limits.

Returns:

left, right – The current x-axis limits in data coordinates.

Return type:

(float, float)

get_ylabel()#

Get the ylabel text string.

get_ylim()#

Returns the frame’s y-axis limits.

Returns:

bottom, top – The current y-axis limits in data coordinates.

Return type:

(float, float)

get_zlabel()#

Get the zlabel text string.

get_zlim()#

Returns the frame’s z-axis limits.

Returns:

bottom, top – The current z-axis limits in data coordinates.

Return type:

(float, float)

graph(x, y, xerr=None, yerr=None, options='P', **kwargs)#

Create and plot a ROOT TGraph from array-like input.

The graph creation is delegated to root_helpers.graph().

Parameters:

  • x (float or array-like, shape (n, )) – The data positions.

  • y (float or array-like, shape (n, )) – The data positions.

  • xerr (float or array-like, shape (n, ), optional) – Error bar sizes in the x and y directions. The default is None, in which case no error bars are added in this direction.

  • yerr (float or array-like, shape (n, ), optional) – Error bar sizes in the x and y directions. The default is None, in which case no error bars are added in this direction.

  • options (str, optional) – Additional options to pass to Draw(). The default is ‘P’.

  • **kwargs (formatting options, optional) – Formatting options passed to plot().

Returns:

TGraph object created from input arrays.

Return type:

ROOT.TGraph or ROOT.TGraphErrors

legend(loc, options='', **kwargs)#

Place a legend on the Axes.

Parameters:

  • loc (tuple) –

    Legend location either as:

    • (w, h): The width and height of the legend in percentage of the current pad size. The position will be automatically defined at painting time.

    • (x1, y1, x2, y2): The coordinates of the legend in the current pad (in normalised coordinates by default).

    Unlike matplotlib, loc must be specified when creating the legend.

  • options (str, optional) – Additional options to pass to TLegend::Draw().

  • **kwargs (formatting options, optional) –

    kwargs are used to specify properties like legend line, fill, and text attributes. See the ROOT docs for available options:

    You can also set the number of columns with the ‘ncol’ kwarg and the border size with the ‘bordersize’ kwarg. Note that some formatting options may not work if the ATLAS style settings have been applied.

property pad#

Returns the axes’ TPad object.

plot(obj, options='', expand=True, label=None, labelfmt=None, **kwargs)#

Plot object on these axes.

Note that Axes.cd() does not need to be called before Axes.plot(); this is done automatically.

Parameters:

  • obj (plottable ROOT object) – The object to plot. This object should be a plottable ROOT object, such as a TH1, TGraph, TF1, etc., and it must have a Draw() method, otherwise a TypeError is raised.

  • options (str, optional) – Additional options to pass to Draw().

  • expand (bool, optional) – Expand the axes to the object being plotted. True be default. Only certain objects will trigger the expansion of the axes; currently these objects are TH1, THStack, TGraph, TMultiGraph, TLine, and their derived classes.

  • label (str, optional) – Object label to pass to legend.

  • labelfmt (str, optional) – If the label option is given, you can also specify the formatting options passed to TLegend::AddEntry(). Note that some formatting options may not work if the ATLAS style settings have been applied.

  • **kwargs (formatting options, optional) –

    kwargs are used to specify properties like marker, line, and fill attributes. See the ROOT docs for available options:

    The kwarg syntax is the same as the equivalent ROOT attribute setter function, but in all lower case and without the ‘Set’ prefix. For example, to set the marker style, use markerstyle=..., which calls SetMarkerStyle(...).

plot2d(obj, options='', label=None, labelfmt=None, **kwargs)#

Plot object with two independent variables on these axes.

Here, obj is normally a TH2 histogram, although this is not required. Unlike plot(), where an object is plotted on an already-existing frame, this function takes the object itself as the axes’ “frame”. This is always the case unless the “SAME” option is used to plot obj; here, the axes’ frame is not replaced with obj. If the axes’ frame already exists as a TH1F object (the default when an Axes object is created), it is deleted and replaced with obj.

See plot() for full documentation of the other options.

set_pad_margins(left=None, right=None, bottom=None, top=None)#

Set the pad margin between the axes and the outer edge of the pad.

Parameters:

  • left (float, optional) – Margin sizes in NDC units [0, 1]. The default is None (use default margin).

  • right (float, optional) – Margin sizes in NDC units [0, 1]. The default is None (use default margin).

  • bottom (float, optional) – Margin sizes in NDC units [0, 1]. The default is None (use default margin).

  • top (float, optional) – Margin sizes in NDC units [0, 1]. The default is None (use default margin).

set_xlabel(xlabel, loc=None, **kwargs)#

Set the label for the x-axis.

Parameters:

  • xlabel (str) – The label text.

  • loc ({'center', 'right'}) – The label position. The default is the same as ROOT’s default x-axis title position (right).

  • **kwargs (formatting options, optional) –

    kwargs are used to specify the axis attributes. See the ROOT docs for available options:

    The kwarg syntax is the same as the equivalent ROOT attribute setter function, but in all lower case and without the ‘Set’ prefix. For example, to set the axis title size, use titlesize=..., which calls SetTitleSize(...).

set_xlim(left=None, right=None)#

Sets the frame’s x-axis limits.

Parameters:

  • left (float, optional) –

    The left xlim in data coordinates. Passing None leaves the limit unchanged.

    The left and right xlims may also be passed as the tuple (left, right) as the first positional argument (or as the left keyword argument).

  • right (float, optional) – The right xlim in data coordinates. Passing None leaves the limit unchanged.

Returns:

left, right – The new x-axis limits in data coordinates.

Return type:

(float, float)

Examples

>>> set_xlim(left, right)
>>> set_xlim((left, right))
>>> left, right = set_xlim(left, right)

One limit may be left unchanged.

>>> set_xlim(right=right_lim)
Returns:

left, right – The new x-axis limits in data coordinates.

Return type:

(float, float)

set_xscale(value)#

Set the x-axis scale.

Parameters:

value ({"linear", "log"}) – The axis scale type to apply.

set_ylabel(ylabel, loc=None, **kwargs)#

Set the label for the y-axis.

Parameters:

  • ylabel (str) – The label text.

  • loc ({'center', 'top'}) – The label position. The default is the same as ROOT’s default y-axis title position (top).

  • **kwargs (formatting options, optional) – See set_xlabel() for usage.

set_ylim(bottom=None, top=None)#

Sets the frame’s y-axis limits.

Parameters:

  • bottom (scalar, optional) –

    The bottom ylim in data coordinates. Passing None leaves the limit unchanged.

    The bottom and top ylims may be passed as the tuple (bottom, top) as the first positional argument (or as the bottom keyword argument).

  • top (scalar, optional) – The top ylim in data coordinates. Passing None leaves the limit unchanged.

Examples

>>> set_ylim(bottom, top)
>>> set_ylim((bottom, top))
>>> bottom, top = set_ylim(bottom, top)

One limit may be left unchanged.

>>> set_ylim(top=top_lim)
Returns:

bottom, top – The new y-axis limits in data coordinates.

Return type:

(float, float)

set_yscale(value)#

Set the y-axis scale.

Parameters:

value ({"linear", "log"}) – The axis scale type to apply.

set_zlabel(zlabel, loc=None, **kwargs)#

Set the label for the z-axis.

Parameters:

  • zlabel (str) – The label text.

  • loc ({'center', 'top'}) – The label position. The default is the same as ROOT’s default z-axis title position (top).

  • **kwargs (formatting options, optional) – See set_xlabel() for usage.

set_zlim(bottom=None, top=None)#

Sets the frame’s z-axis limits.

See See set_ylim() for full documentation.

set_zscale(value)#

Set the z-axis scale.

Parameters:

value ({"linear", "log"}) – The axis scale type to apply.

text(x, y, text, size=None, font=None, align=None, color=None, alpha=None, angle=None)#

Draws text on these axes using the ROOT TLatex class.

Parameters:

  • x (float) –

    The x- and y-coordinates of the text in NDC units [0, 1].

    This x-coordinate is left-aligned and the y-coordinate is top-aligned unless the align argument is given.

  • y (float) –

    The x- and y-coordinates of the text in NDC units [0, 1].

    This x-coordinate is left-aligned and the y-coordinate is top-aligned unless the align argument is given.

  • text (str) – The text to draw. ROOT TLatex syntax is supported.

  • size (float, optional) – Text size.

  • font (int, optional) – ROOT font code.

  • align (int, optional) – ROOT text-alignment code.

  • color (int, optional) – ROOT text-color code.

  • alpha (float, optional) – Text alpha.

  • angle (float, optional) – Text angle in degrees.

Returns:

The TLatex object for this text.

Return type:

ROOT.TLatex

class atlasplots.core.Figure(name='', title='', figsize=None)#

Bases: object

A matplotlib-like Figure object powered by ROOT.

A Figure object is a wrapper around a ROOT TCanvas. Figure provides matplotlib-like syntax to change figure parameters while still providing access to the underlying ROOT objects.

Parameters:

  • name (str, optional) – Figure (canvas) name.

  • title (str, optional) – Figure (canvas) title.

  • figsize ((float, float), optional) – Figure (canvas) dimension (width, height) in pixels. The default dimensions are (800, 600).

add_axes(ax)#

Add axes to the figure.

Parameters:

ax (Axes) – The Axes object to add.

property axes#

Returns the figure’s axes.

property canvas#

Returns the figure’s TCanvas object.

savefig(fname, options='')#

Save the figure using TCanvas::SaveAs().

Parameters:

  • fname (str or path-like) – File name.

  • options (str, optional) – Addition options to pass to TCanvas::SaveAs().

subplots(nrows=1, ncols=1, width_ratios=None, height_ratios=None, wspace=None, hspace=None)#

Add a set of subplots to this figure.

Parameters:

  • nrows (int, default: 1) – Number of rows/columns of the subplot grid.

  • ncols (int, default: 1) – Number of rows/columns of the subplot grid.

  • width_ratios (array-like of length ncols, optional) – Defines the relative widths of the columns. Each column gets a relative width of width_ratios[i] / sum(width_ratios). If not given, all columns will have the same width.

  • height_ratios (array-like of length nrows, optional) – Defines the relative heights of the rows. Each row gets a relative height of height_ratios[i] / sum(height_ratios). If not given, all rows will have the same height.

  • wspace (float, optional) – The amount of width reserved for space between subplots, expressed as a fraction of the average axis width. Not implemented yet…

  • hspace (float, optional) – The amount of height reserved for space between subplots, expressed as a fraction of the average axis height. Not implemented yet…

Returns:

axs – Either a single Axes object or an array of Axes objects if more than one subplot was created.

Return type:

Axes or array of Axes.

atlasplots.root_helpers module#

atlasplots.root_helpers#

This module contains helper functions for dealing with ROOT objects, especially histograms and graphs.

copyright:

  1. 2020-2021 Joey Carter.

license:

MIT, see LICENSE for more details.

atlasplots.root_helpers.get_color_code(color)#

Get ROOT colour code from arbitrary input.

Parameters:

color (str, tuple, int) –

The input colour. Must be one of:

  • Name of ROOT’s predefined colours (str): white, black, gray, red, green, blue, yellow, magenta, cyan, orange, spring, teal, azure, violet, pink.

  • Colour hex code (str beginning with ‘#’).

  • RGB (red, green, blue) tuple of integers in the range [0, 255] or floats in the range [0, 1].

  • ROOT colour code (int). If this is the case, colour is returned as is.

atlasplots.root_helpers.graph(x, y, xerr=None, yerr=None)#

Create a ROOT TGraph from array-like input.

Parameters:

  • x (float or array-like, shape (n, )) – The data positions.

  • y (float or array-like, shape (n, )) – The data positions.

  • xerr (float or array-like, shape (n, ), optional) – Error bar sizes in the x and y directions. The default is None, in which case no error bars are added in this direction.

  • yerr (float or array-like, shape (n, ), optional) – Error bar sizes in the x and y directions. The default is None, in which case no error bars are added in this direction.

Returns:

TGraph object created from input arrays.

Return type:

ROOT.TGraph or ROOT.TGraphErrors

atlasplots.root_helpers.graph_xmax(graph)#

Returns the graph’s maximum x-value, including error bars where relevant.

Recall that you can always retrieve the maximum point x-value of a TGraph object with ROOT.TMath.MaxElement(gr.GetN(), gr.GetX()).

The value returned depends on the type of TGraph given:

  • TGraph: the graphs’s maximum point value.

  • TGraphErrors: the graph’s maximum point + error value.

  • TGraphAsymmErrors: the graph’s maximum point + error_high value.

Parameters:

graph (ROOT TGraph, TGraphErrors or TGraphAsymmErrors) – The ROOT graph object.

Returns:

xmax – Maximum x-value of graph.

Return type:

scalar

atlasplots.root_helpers.graph_xmin(graph, only_pos=False)#

Returns the graph’s minimum x-value, including error bars where relevant.

Recall that you can always retrieve the minimum point x-value of a TGraph object with ROOT.TMath.MinElement(gr.GetN(), gr.GetX()).

The value returned depends on the type of TGraph given:

  • TGraph: the graphs’s minimum point value.

  • TGraphErrors: the graph’s minimum point - error value.

  • TGraphAsymmErrors: the graph’s minimum point - error_low value.

Parameters:

  • graph (ROOT TGraph, TGraphErrors or TGraphAsymmErrors) – The ROOT graph object.

  • only_pos (bool, optional) –

    Only include positive values when searching for the minimum. All points are included by default.

    This option is useful for setting the x-axis limits when it is in log scale.

Returns:

xmin – Minimum x-value of graph.

Return type:

scalar

atlasplots.root_helpers.graph_ymax(graph)#

Returns the graph’s maximum y-value, including error bars where relevant.

Recall that you can always retrieve the maximum point y-value of a TGraph object with ROOT.TMath.MaxElement(gr.GetN(), gr.GetY()).

The value returned depends on the type of TGraph given:

  • TGraph: the graphs’s maximum point value.

  • TGraphErrors: the graph’s maximum point + error value.

  • TGraphAsymmErrors: the graph’s maximum point + error_high value.

Parameters:

graph (ROOT TGraph, TGraphErrors or TGraphAsymmErrors) – The ROOT graph object.

Returns:

ymax – Maximum y-value of graph.

Return type:

scalar

atlasplots.root_helpers.graph_ymin(graph, only_pos=False)#

Returns the graph’s minimum y-value, including error bars where relevant.

Recall that you can always retrieve the minimum point y-value of a TGraph object with ROOT.TMath.MinElement(gr.GetN(), gr.GetY()).

The value returned depends on the type of TGraph given:

  • TGraph: the graphs’s minimum point value.

  • TGraphErrors: the graph’s minimum point - error value.

  • TGraphAsymmErrors: the graph’s minimum point - error_low value.

Parameters:

  • graph (ROOT TGraph, TGraphErrors or TGraphAsymmErrors) – The ROOT graph object.

  • only_pos (bool, optional) –

    Only include positive values when searching for the minimum. All points are included by default.

    This option is useful for setting the y-axis limits when it is in log scale.

Returns:

ymin – Minimum y-value of graph.

Return type:

scalar

atlasplots.root_helpers.hist_max(hist, include_err=False, include_overflow=False, axis=None)#

Returns the histogram’s maximum bin content (with or without bin errors).

Parameters:

  • hist (ROOT TH1, TH2 or TH3) – The ROOT histogram.

  • include_err (bool, optional) – Include bin errors when searching for the maximum. If True, the returned value(s) is hist.GetBinContent(i) + hist.GetBinErrorUp(i), where i is the index of the maximum bin. By default, bin errors are not included.

  • include_overflow (bool, optional) – If True, the over- and underflow bins will be included in the search for the maximum bin. These bins are excluded by default.

  • axis (None or int or tuple of ints, optional) – Axis or axes along which to operate, as defined in numpy.amax(). By default, flattened input is used.

Returns:

max – Maximum of bin contents of hist. If axis is None, the result is a scalar value. If axis is given, the result is an array of dimension a.ndim - 1.

Return type:

numpy.ndarray or scalar

atlasplots.root_helpers.hist_min(hist, include_err=False, include_overflow=False, only_pos=False, axis=None)#

Returns the histogram’s minimum bin content (with or without bin errors).

Parameters:

  • hist (ROOT TH1, TH2 or TH3) – The ROOT histogram.

  • include_err (bool, optional) – Include bin errors when searching for the minimum. If True, the returned value(s) is hist.GetBinContent(i) - hist.GetBinErrorLow(i), where i is the index of the minimum bin. By default, bin errors are not included.

  • include_overflow (bool, optional) – If True, the over- and underflow bins will be included in the search for the minimum bin. These bins are excluded by default.

  • only_pos (bool, optional) –

    Only include positive bins when searching for the minimum. All bins are included by default.

    This option is useful for setting the y-axis limits when it is in log scale.

  • axis (None or int or tuple of ints, optional) – Axis or axes along which to operate, as defined in numpy.amin(). By default, flattened input is used.

Returns:

min – Minimum of bin contents of hist. If axis is None, the result is a scalar value. If axis is given, the result is an array of dimension a.ndim - 1.

Return type:

numpy.ndarray or scalar

atlasplots.root_helpers.hist_to_graph(hist, bin_err='none', show_bin_width=False, norm=False)#

Convert histogram (TH1) to graph (TGraph).

Parameters:

  • hist (ROOT TH1) – The ROOT histogram.

  • bin_err (str, TH1.EBinErrorOpt, optional) –

    Type of bin error to use. Choose from the following options:

    • ’none’: use the bin-error option already defined in hist. This is the default option.

    • ’normal’ or ROOT.TH1.EBinErrorOpt.kNormal: errors with Normal (Wald) approximation: errorUp = errorLow = sqrt(N).

    • ’poisson’ or ROOT.TH1.EBinErrorOpt.kPoisson: errors from Poisson interval at 68.3% (1 sigma).

    • ’poisson2’ or ROOT.TH1.EBinErrorOpt.kPoisson2: errors from Poisson interval at 95% CL (~2 sigma).

    For more details, see TH1.EBinErrorOpt.

  • show_bin_width (bool, optional) – If True, use graph x error bars to show bin width and place marker at centre of bin. The x error bars are set to 0 by default.

  • norm (bool, optional) – Normalize the resulting graph such that the y value of each point is 1 and the error is y_err/y. The x values and their errors remain the same. This is useful for showing the relative error of a histogram in a ratio plot, for example.

Returns:

TGraph equivalent of hist.

Return type:

ROOT TGraphAsymmErrors

atlasplots.root_helpers.multigraph_xmax(multigraph)#

Interface to graph_xmax if the graph is a ROOT TMultiGraph.

Parameters:

multigraph (ROOT TMultiGraph) – The ROOT multi-graph object.

Returns:

xmax – Maximum x-value of graph.

Return type:

scalar

atlasplots.root_helpers.multigraph_xmin(multigraph, only_pos=False)#

Interface to graph_xmin if the graph is a ROOT TMultiGraph.

Parameters:

  • multigraph (ROOT TMultiGraph) – The ROOT multi-graph object.

  • only_pos (bool, optional) – Only include positive values when searching for the minimum. All points are included by default. See graph_xmin.

Returns:

xmin – Minimum x-value of graph.

Return type:

scalar

atlasplots.root_helpers.multigraph_ymax(multigraph)#

Interface to graph_ymax if the graph is a ROOT TMultiGraph.

Parameters:

multigraph (ROOT TMultiGraph) – The ROOT multi-graph object.

Returns:

ymax – Maximum y-value of graph.

Return type:

scalar

atlasplots.root_helpers.multigraph_ymin(multigraph, only_pos=False)#

Interface to graph_ymin if the graph is a ROOT TMultiGraph.

Parameters:

  • multigraph (ROOT TMultiGraph) – The ROOT multi-graph object.

  • only_pos (bool, optional) – Only include positive values when searching for the minimum. All points are included by default. See graph_ymin.

Returns:

ymin – Minimum y-value of graph.

Return type:

scalar

atlasplots.root_helpers.set_graphics_attributes(obj, **kwargs)#

Set an object’s graphics attributes.

Parameters: