plot_util

Some utils for plot functions.

Functions:

get_cms_label(ax, llabel)	Helper function to get the CMS label configuration.
get_attr_or_aux(proc, attr, default)
round_dynamic(value)	Rounds a value at various scales to a subjective, sensible precision.
apply_settings(instances, settings[, ...])	applies settings from settings dictionary to a list of order objects containers
hists_merge_cutflow_steps(hists)	Make 'step' axis uniform among a set of histograms.
apply_process_settings(hists[, process_settings])	applies settings from process_settings dictionary to the process_insts
apply_process_scaling(hists)
apply_variable_settings(hists, variable_insts)	applies settings from variable_settings dictionary to the variable_insts; the rebin, overflow, underflow, and slice settings are directly applied to the histograms
use_flow_bins(h_in, axis_name[, underflow, ...])	Adds content of the flow bins of axis axis_name of histogram h_in to the first/last bin.
apply_density(hists[, density])	Scales number of histogram entries to bin widths.
remove_residual_axis_single(h, ax_name[, ...])
remove_residual_axis(hists, ax_name[, ...])	Removes axis named 'ax_name' if existing and there is only a single bin in the axis; raises Exception otherwise
prepare_style_config(config_inst, ...[, ...])	small helper function that sets up a default style config based on the instances of the config, category and variable
prepare_stack_plot_config(hists[, ...])	Prepares a plot config with one entry to create plots containing a stack of backgrounds with uncertainty bands, unstacked processes as lines and data entrys with errorbars.
split_ax_kwargs(kwargs)	Split the given dictionary into two dictionaries based on the keys that are valid for matplotlib's ax.set() function, and all others, potentially accepted by apply_ax_kwargs().
apply_ax_kwargs(ax, kwargs)	Apply the given keyword arguments to the given axis, splitting them into those that are valid for ax.set() and those that are not, and applying them separately.
get_position(minimum, maximum[, factor, ...])	get a relative position between a min and max value based on the scale
join_labels(*labels[, inline_sep, multiline_sep])
reduce_with(spec, values)	Reduce an array of values to a single value using the function indicated by spec.
broadcast_1d_to_nd(x, final_shape[, axis])	Helper function to broadcast a 1d array x to an nd array with shape final_shape.
broadcast_nminus1d_to_nd(x, final_shape[, axis])	Helper function to broadcast a (n-1)d array x to an nd array with shape final_shape.
get_profile_width(h_in[, axis])	Function that takes a histogram h_in and returns the mean and width when profiling over the axis axis.
get_profile_variations(h_in[, axis])	Returns a profile histogram plus the up and down variations of the profile from a normal histogram with N-1 axes.
blind_sensitive_bins(hists, config_inst, ...)	Function that takes a histogram h_in and blinds the values of the profile over the axis axis that are below a certain threshold threshold.
rebin_equal_width(hists, axis_name)	In a dictionary, rebins an axis named axis_name of all histograms to have the same amount of bins but with equal width.
apply_label_placeholders(label[, apply, skip])
remove_label_placeholders(label[, keep, drop])
calculate_stat_error(hist, error_type)

get_cms_label(ax, llabel)

Helper function to get the CMS label configuration.

Parameters:

• ax (Axes) – The axis to plot the CMS label on.

• llabel (str) – The left label of the CMS label.

Return type:

dict

Returns:

A dictionary with the CMS label configuration.

get_attr_or_aux(proc, attr, default)

Return type:

Any

round_dynamic(value)

Rounds a value at various scales to a subjective, sensible precision. Rounding rules:

• 0 -> 0 (int)

• (0, 1) -> round to 1 significant digit (float)

• [1, 10) -> round to 1 significant digit (int)

• [10, inf) -> round to 2 significant digits (int)

Parameters:

value (int | float) – The value to round.

Return type:

int | float

Returns:

The rounded value.

apply_settings(instances, settings, parent_check=None)

applies settings from settings dictionary to a list of order objects containers

Parameters:

• instances (Iterable[od.AuxDataMixin]) – List of order instances to apply settings to.

• settings (dict[str, Any] | None) – Dictionary of settings to apply on the instances. Each key should correspond to the name of an instance and each value should be a dictionary with attributes that will be set on the instance either as a attribute or as an auxiliary.

• parent_check (Callable[[od.AuxDataMixin, str], bool] | None, default: None) – Function that checks if an instance has a parent with a given name.

Return type:

None

hists_merge_cutflow_steps(hists)

Make ‘step’ axis uniform among a set of histograms. Takes a dict of 1D histogram objects with a single ‘step’ axis of type StrCategory, computes the full list of possible ‘step’ values across all histograms, and returns a dict of histograms whose ‘step’ axis has a corresponding, uniform structure. The values and variances inserted for missing ‘step’ are taken from the previous existing step.

Return type:

dict

apply_process_settings(hists, process_settings=None)

applies settings from process_settings dictionary to the process_insts

Return type:

tuple[dict[Hashable, hist.Hist], dict[str, Any]]

apply_process_scaling(hists)

Return type:

dict[Hashable, Hist]

apply_variable_settings(hists, variable_insts, variable_settings=None)

applies settings from variable_settings dictionary to the variable_insts; the rebin, overflow, underflow, and slice settings are directly applied to the histograms

Return type:

tuple[dict[Hashable, hist.Hist], dict[od.Variable, dict[str, Any]]]

use_flow_bins(h_in, axis_name, underflow=True, overflow=True)

Adds content of the flow bins of axis axis_name of histogram h_in to the first/last bin.

Parameters:

• h_in (hist.Hist) – Input histogram

• axis_name (str | int) – Name or index of the axis of interest.

• underflow (bool, default: True) – Whether to add the content of the underflow bin to the first bin of axis *axis_name.

• overflow (bool, default: True) – Whether to add the content of the overflow bin to the last bin of axis axis_name.

Return type:

hist.Hist

Returns:

Copy of the histogram with underflow and/or overflow content added to the first/last bin of the histogram.

apply_density(hists, density=True)

Scales number of histogram entries to bin widths.

Return type:

dict

remove_residual_axis_single(h, ax_name, max_bins=1, select_value=None)

Return type:

Hist

remove_residual_axis(hists, ax_name, max_bins=1, select_value=None)

Removes axis named ‘ax_name’ if existing and there is only a single bin in the axis; raises Exception otherwise

Return type:

dict

prepare_style_config(config_inst, category_inst, variable_inst, density=False, shape_norm=False, yscale='', **kwargs)

small helper function that sets up a default style config based on the instances of the config, category and variable

Return type:

dict

prepare_stack_plot_config(hists, shape_norm=False, hide_stat_errors=None, shift_insts=None, **kwargs)

Prepares a plot config with one entry to create plots containing a stack of backgrounds with uncertainty bands, unstacked processes as lines and data entrys with errorbars.

Return type:

OrderedDict

split_ax_kwargs(kwargs)

Split the given dictionary into two dictionaries based on the keys that are valid for matplotlib’s ax.set() function, and all others, potentially accepted by apply_ax_kwargs().

Return type:

tuple[dict[str, Any], dict[str, Any]]

apply_ax_kwargs(ax, kwargs)

Apply the given keyword arguments to the given axis, splitting them into those that are valid for ax.set() and those that are not, and applying them separately.

Return type:

None

get_position(minimum, maximum, factor=1.4, logscale=False)

get a relative position between a min and max value based on the scale

Return type:

float

join_labels(*labels, inline_sep=',', multiline_sep='\\n')

Return type:

str

reduce_with(spec, values)

Reduce an array of values to a single value using the function indicated by spec. Intended as a helper for resolving range specifications supplied as strings.

Supported specifiers are: :rtype: float

• ‘min’: minimum value

• ‘max’: maximum value

• ‘maxabs’: the absolute value of the maximum or minimum, whichever is larger

• ‘minabs’: the absolute value of the maximum or minimum, whichever is smaller

A hyphen (-) can be prefixed to any specifier to return its negative.

Callables can be passed as spec and should take a single array-valued argument and return a single value. Floats passes as specifiers will be returned directly.

broadcast_1d_to_nd(x, final_shape, axis=1)

Helper function to broadcast a 1d array x to an nd array with shape final_shape. The length of x should be the same as final_shape[axis].

Return type:

array

broadcast_nminus1d_to_nd(x, final_shape, axis=1)

Helper function to broadcast a (n-1)d array x to an nd array with shape final_shape. final_shape should be the same as x.shape except that the axis axis is missing.

Return type:

array

get_profile_width(h_in, axis=1)

Function that takes a histogram h_in and returns the mean and width when profiling over the axis axis.

Return type:

tuple[array, array]

get_profile_variations(h_in, axis=1)

Returns a profile histogram plus the up and down variations of the profile from a normal histogram with N-1 axes. The axis given is profiled over and removed from the final histograms.

Return type:

dict[str, Hist]

blind_sensitive_bins(hists, config_inst, threshold)

Function that takes a histogram h_in and blinds the values of the profile over the axis axis that are below a certain threshold threshold. The function needs an entry in the process_groups key of the config auxiliary that is called “signals” to know, where the signal processes are defined (regex allowed). The histograms are not changed inplace, but copies of the modified histograms are returned.

Return type:

dict[Process, Hist]

rebin_equal_width(hists, axis_name)

In a dictionary, rebins an axis named axis_name of all histograms to have the same amount of bins but with equal width. This is achieved by using integer edge values starting at 0. The original edge values are returned as well. Bin contents are not changed but copied to the rebinned histograms.

Parameters:

• hists (dict[Hashable, Hist]) – Dictionary of histograms to rebin.

• axis_name (str) – Name of the axis to rebin.

Return type:

tuple[dict[Hashable, Hist], ndarray]

Returns:

Tuple of the rebinned histograms and the new bin edges.

apply_label_placeholders(label, apply=None, skip=None, **kwargs)

Return type:

str

Interprets placeholders in the format “__NAME__” in a label and returns an updated label. Currently supported placeholders are:

• SHORT: removes everything (and including) the placeholder

• BREAK: inserts a line break

• SCALE: inserts a scale factor, passed as “scale” in kwargs; when “scale_format” is given

  as well, the scale factor is formatted accordingly

apply and skip can be used to de/select certain placeholders.

remove_label_placeholders(label, keep=None, drop=None)

Return type:

str

calculate_stat_error(hist, error_type)

Return type:

dict

Calculate the error to be plotted for the given histogram hist. Supported error types are:

• ‘variance’: the plotted error is the square root of the variance for each bin

• ‘poisson_unweighted’: the plotted error is the poisson error for each bin

• ‘poisson_weighted’: the plotted error is the poisson error for each bin, weighted by the variance