Package references

Histogramming functions

exception plothist.histogramming.RangeWarning

plothist.histogramming.create_axis(bins, range=None, data=None, overflow=False, underflow=False)

Create an axis object for histogram binning based on the input data and parameters.

Parameters:

• bins (int or list[float]) – The number of bins or bin edges for the axis.

• range (None or tuple[float | str, float | str], optional) – The range of the axis. If None, it will be determined based on the data. Default is None.

• data (list[float] or np.ndarray, optional) – The input data for determining the axis range. Default is None.

• overflow (bool, optional) – Whether to include an overflow bin. If False, the upper edge of the last bin is inclusive. Default is False.

• underflow (bool, optional) – Whether to include an underflow bin. Default is False.

Returns:

An axis object for histogram binning. The axis type is determined based on the input parameters. If bins is an integer, a regular axis is returned. If bins is an array-like, a variable axis is returned.

Return type:

Axis object

Raises:

• ValueError – If the range parameter is invalid or not finite.

• ValueError – If the number of bins is not positive.

• ValueError – If the range parameter contains “min” or “max” but the data is empty.

plothist.histogramming.flatten_2d_hist(hist)

Flatten a 2D histogram into a 1D histogram.

Parameters:

hist (bh.Histogram) – The 2D histogram to be flattened.

Returns:

The flattened 1D histogram.

Return type:

bh.Histogram

Raises:

ValueError – If the input histogram is not 2D.

plothist.histogramming.make_2d_hist(data=None, bins=None, range=(None, None), weights=1, mute_warning=False)

Create a 2D histogram object and fill it with the provided data.

Parameters:

• data (list[np.ndarray] or np.ndarray, optional) – 2D array-like data used to fill the histogram (default is None). If None is provided, an empty histogram is returned.

• bins (Sequence[int | Sequence[float]], optional) – Binning specification for each dimension of the histogram (if None, it will be set to [50, 50]). Each element of the tuple represents the number of bins for the corresponding dimension. Also support explicit bin edges specification (for non-constant bin size).

• range (tuple[tuple[float | str, float | str] | None, tuple[float | str, float | str] | None], optional) – The range of values to consider for each dimension of the histogram (default is (None, None)). If None, the range is determined from the data for that dimension. The tuple should have the same length as the data.

• weights (float or list[float] or np.ndarray, optional) – Weight(s) to apply to the data points (default is 1). If a float, a single weight is applied to all data points. If an array-like, weights are applied element-wise.

• mute_warning (bool, optional) – Whether to mute warnings about data outside the binning range (default is False).

Returns:

histogram – The filled 2D histogram object.

Return type:

bh.Histogram

Raises:

ValueError – If the data does not have two components or if the lengths of x and y are not equal.

Warns:

RangeWarning – If more than 1% of the data is outside of the binning range.

plothist.histogramming.make_hist(data=None, bins=50, range=None, weights=1, mute_warning=False)

Create a histogram object and fill it with the provided data.

Parameters:

• data (list[float] or np.ndarray, optional) – 1D array-like data used to fill the histogram (default is None). If None is provided, an empty histogram is returned.

• bins (int or list[float], optional) – Binning specification for the histogram (default is 50). If an integer, it represents the number of bins. If a list, it should be the explicit list of all bin edges.

• range (tuple[float | str, float | str], optional) – The range of values to consider for the histogram bins (default is None). If None, the range is determined from the data.

• weights (float or list[float] or np.ndarray, optional) – Weight(s) to apply to the data points (default is 1). If a float, a single weight is applied to all data points. If an array-like, weights are applied element-wise.

• mute_warning (bool, optional) – Whether to mute warnings about data outside the binning range (default is False).

Returns:

histogram – The filled histogram object.

Return type:

bh.Histogram

Warns:

RangeWarning – If more than 1% of the data is outside of the binning range.

Plotting functions

Collection of functions to plot histograms

plothist.plotters.create_comparison_figure(figsize=(6, 5), nrows=2, gridspec_kw=None, hspace=0.15)

Create a figure with subplots for comparison.

Parameters:

• figsize (tuple[float, float], optional) – Figure size in inches. Default is (6, 5). If None is provided, the default matplotlib figure size from rcParams[“figure.figsize”] is used.

• nrows (int, optional) – Number of rows in the subplot grid. Default is 2.

• gridspec_kw (dict[str, Any] | None, optional) – Additional keyword arguments for the GridSpec. Default is None. If None is provided, this is set to {“height_ratios”: [4, 1]}.

• hspace (float, optional) – Height spacing between subplots. Default is 0.15.

Returns:

• fig (matplotlib.figure.Figure) – The created figure.

• axes (np.ndarray) – Array of Axes objects representing the subplots.

Return type:

tuple[Figure, ndarray]

plothist.plotters.plot_2d_hist(hist, fig=None, ax=None, ax_colorbar=None, pcolormesh_kwargs=None, colorbar_kwargs=None, square_ax=True)

Plot a 2D histogram using a pcolormesh plot and add a colorbar.

Parameters:

• hist (bh.Histogram) – The 2D histogram to plot.

• fig (matplotlib.figure.Figure | None, optional) – The Figure instance for plotting. If fig, ax and ax_colorbar are all None, a new figure will be created. Default is None.

• ax (matplotlib.axes.Axes | None, optional) – The Axes instance for plotting. If fig, ax and ax_colorbar are all None, a new figure will be created. Default is None.

• ax_colorbar (matplotlib.axes.Axes | None, optional) – The Axes instance for the colorbar. If fig, ax and ax_colorbar are all None, a new figure will be created. Default is None.

• pcolormesh_kwargs (dict[str, Any] | None, optional) – Additional keyword arguments forwarded to ax.pcolormesh(). Default is None.

• colorbar_kwargs (dict[str, Any] | None, optional) – Additional keyword arguments forwarded to ax.get_figure().colorbar(). Default is None.

• square_ax (bool, optional) – Whether to make the main ax square. Default is True.

Return type:

tuple[Figure, Axes, Axes]

plothist.plotters.plot_2d_hist_with_projections(hist, xlabel=None, ylabel=None, ylabel_x_projection=None, xlabel_y_projection=None, colorbar_label=None, offset_x_labels=False, pcolormesh_kwargs=None, colorbar_kwargs=None, plot_hist_kwargs=None, figsize=(6, 6))

Plot a 2D histogram with projections on the x and y axes.

Parameters:

• hist (bh.Histogram) – The 2D histogram to plot.

• xlabel (str | None, optional) – Label for the x axis. Default is None.

• ylabel (str | None, optional) – Label for the y axis. Default is None.

• ylabel_x_projection (str | None, optional) – Label for the y axis of the x projection. Default is None.

• xlabel_y_projection (str | None, optional) – Label for the x axis of the y projection. Default is None.

• colorbar_label (str | None, optional) – Label for the colorbar. Default is None.

• offset_x_labels (bool, optional) – Whether to offset the x labels to avoid overlapping with the exponent label (i.e. “10^X”) of the axis. Default is False.

• pcolormesh_kwargs (dict[str, Any] | None, optional) – Keyword arguments for the pcolormesh call. Default is None.

• colorbar_kwargs (dict[str, Any] | None, optional) – Keyword arguments for the colorbar call. Default is None.

• plot_hist_kwargs (dict[str, Any] | None, optional) – Keyword arguments for the plot_hist call (x and y projections). Default is None.

• figsize (tuple[float, float], optional) – Figure size in inches. Default is (6, 6). To get square bins if the figure is not square shaped, be sure to set the bins and the ranges of the histogram according to the ratio of the figure width and height.

Returns:

• fig (matplotlib.figure.Figure) – The figure.

• ax_2d (matplotlib.axes.Axes) – The axes for the 2D histogram.

• ax_x_projection (matplotlib.axes.Axes) – The axes for the x projection.

• ax_y_projection (matplotlib.axes.Axes) – The axes for the y projection.

• ax_colorbar (matplotlib.axes.Axes) – The axes for the colorbar.

Return type:

tuple[Figure, Axes, Axes, Axes, Axes]

plothist.plotters.plot_comparison(h1, h2, ax, xlabel=None, h1_label='h1', h2_label='h2', comparison='ratio', comparison_ylabel=None, comparison_ylim=None, h1_uncertainty_type='symmetrical', **plot_hist_kwargs)

Plot the comparison between two histograms.

Parameters:

• h1 (bh.Histogram) – The first histogram for comparison.

• h2 (bh.Histogram) – The second histogram for comparison.

• ax (matplotlib.axes.Axes) – The axes to plot the comparison.

• xlabel (str | None, optional) – The label for the x-axis. Default is None.

• h1_label (str, optional) – The label for the first histogram. Default is “h1”.

• h2_label (str, optional) – The label for the second histogram. Default is “h2”.

• comparison (str, optional) – The type of comparison to plot (“ratio”, “split_ratio”, “pull”, “difference”, “relative_difference”, “efficiency”, or “asymmetry”). Default is “ratio”. When the split_ratio option is used, both the h1 and h2 uncertainties are scaled down by the h2 bin contents, and the h2 adjusted uncertainties are shown separately as a hatched area.

• comparison_ylabel (str | None, optional) – The label for the y-axis. If None, the label is the explicit formula used to compute the comparison plot. Default is None.

• comparison_ylim (tuple[float, float] | None, optional) – The y-axis limits for the comparison plot. If None, standard y-axis limits are setup. Default is None.

• h1_uncertainty_type (str, optional) – What kind of bin uncertainty to use for h1: “symmetrical” for the Poisson standard deviation derived from the variance stored in the histogram object, “asymmetrical” for asymmetrical uncertainties based on a Poisson confidence interval. Default is “symmetrical”. Asymmetrical uncertainties are not supported for the asymmetry and efficiency comparisons.

• **plot_hist_kwargs (optional) – Arguments to be passed to plot_hist(), called in case the comparison is “pull”, or plot_error_hist(), called for every other comparison case. In the former case, the default arguments are histtype=”stepfilled” and color=”darkgrey”. In the later case, the default argument is color=”black”.

Returns:

ax – The axes with the plotted comparison.

Return type:

matplotlib.axes.Axes

See also

plot_two_hist_comparison

Compare two histograms and plot the comparison.

plothist.plotters.plot_data_model_comparison(data_hist, stacked_components=None, stacked_labels=None, stacked_colors=None, unstacked_components=None, unstacked_labels=None, unstacked_colors=None, xlabel=None, ylabel=None, data_label='Data', stacked_kwargs=None, unstacked_kwargs_list=None, model_sum_kwargs=None, model_uncertainty=True, model_uncertainty_label='Model stat. unc.', data_uncertainty_type='asymmetrical', fig=None, ax_main=None, ax_comparison=None, plot_only=None, **comparison_kwargs)

Compare data to model. The data uncertainties are computed using the Poisson confidence interval.

Parameters:

• data_hist (bh.Histogram) – The histogram for the data.

• stacked_components (list[bh.Histogram] | None, optional) – The list of histograms to be stacked composing the model. Default is None.

• stacked_labels (list[str] | None, optional) – The labels of the model stacked components. Default is None.

• stacked_colors (list[str] | None, optional) – The colors of the model stacked components. Default is None.

• unstacked_components (list[bh.Histogram] | None, optional) – The list of histograms not to be stacked composing the model. Default is None.

• unstacked_labels (list[str] | None, optional) – The labels of the model unstacked components. Default is None.

• unstacked_colors (list[str] | None, optional) – The colors of the model unstacked components. Default is None.

• xlabel (str | None, optional) – The label for the x-axis. Default is None.

• ylabel (str | None, optional) – The label for the y-axis. Default is None.

• data_label (str, optional) – The label for the data. Default is “Data”.

• stacked_kwargs (dict[str, Any] | None, optional) – The keyword arguments used when plotting the stacked components in plot_hist() or plot_function(), one of which is called only once. Default is None.

• unstacked_kwargs_list (list[dict[str, Any]] | None, optional) – The list of keyword arguments used when plotting the unstacked components in plot_hist() or plot_function(), one of which is called once for each unstacked component. Default is None.

• model_sum_kwargs (dict[str, Any] | None, optional) – The keyword arguments for the plot_hist() function for the sum of the model components. Has no effect if all the model components are stacked or if the model is one unstacked element. The special keyword “show” can be used with a boolean to specify whether to show or not the sum of the model components. Default is None. If None is provided, this is set to {“show”: True, “label”: “Sum”, “color”: “navy”}.

• model_uncertainty (bool, optional) – If False, set the model uncertainties to zeros. Default is True.

• model_uncertainty_label (str, optional) – The label for the model uncertainties. Default is “Model stat. unc.”.

• data_uncertainty_type (str, optional) – What kind of bin uncertainty to use for data_hist: “symmetrical” for the Poisson standard deviation derived from the variance stored in the histogram object, “asymmetrical” for asymmetrical uncertainties based on a Poisson confidence interval. Default is “asymmetrical”.

• fig (matplotlib.figure.Figure | None, optional) – The figure to use for the plot. If fig, ax_main and ax_comparison are all None, a new figure will be created. Default is None.

• ax_main (matplotlib.axes.Axes | None, optional) – The main axes for the histogram comparison. If fig, ax_main and ax_comparison are all None, a new figure will be created. Default is None.

• ax_comparison (matplotlib.axes.Axes | None, optional) – The axes for the comparison plot. If fig, ax_main and ax_comparison are all None, a new figure will be created. Default is None.

• plot_only (str | None, optional) – If “ax_main” or “ax_comparison”, only the main or comparison axis is plotted on the figure. Both axes are plotted if None is specified, which is the default. This can only be used when fig, ax_main and ax_comparison are not provided by the user.

• **comparison_kwargs (optional) – Arguments to be passed to plot_comparison(), including the choice of the comparison function and the treatment of the uncertainties (see documentation of plot_comparison() for details). If they are not provided explicitly, the following arguments are passed by default: h1_label=”Data”, h2_label=”Pred.”, comparison=”split_ratio”.

Returns:

• fig (matplotlib.figure.Figure) – The Figure object containing the plots.

• ax_main (matplotlib.axes.Axes) – The Axes object for the main plot.

• ax_comparison (matplotlib.axes.Axes) – The Axes object for the comparison plot.

Return type:

tuple[Figure, Axes, Axes]

See also

plot_comparison

Plot the comparison between two histograms.

plothist.plotters.plot_error_hist(hist, ax, uncertainty_type='symmetrical', density=False, **kwargs)

Create an errorbar plot from a boost histogram.

Parameters:

• hist (bh.Histogram) – The histogram to plot.

• ax (matplotlib.axes.Axes) – The Axes instance for plotting.

• uncertainty_type (str, optional) – What kind of bin uncertainty to use for hist: “symmetrical” for the Poisson standard deviation derived from the variance stored in the histogram object, “asymmetrical” for asymmetrical uncertainties based on a Poisson confidence interval. Default is “symmetrical”. Asymmetrical uncertainties can only be computed for an unweighted histogram, because the bin contents of a weighted histogram do not follow a Poisson distribution. More information in Notes on statistics. The uncertainties are overwritten if the keyword argument yerr is provided. In the case of a mean histogram, only symmetrical uncertainties are supported and correspond to the standard deviation of the sample and not to a Poisson standard deviation (see Mean histogram (profile plot)).

• density (bool, optional) – Whether to normalize the histogram to unit area. Default is False.

• **kwargs – Additional keyword arguments forwarded to ax.errorbar().

Return type:

None

plothist.plotters.plot_function(func, range, ax, stacked=False, npoints=1000, **kwargs)

Plot a 1D function on a given range.

Parameters:

• func (Callable[[np.ndarray], np.ndarray] | list[Callable[[np.ndarray], np.ndarray]]) – The 1D function or list of functions to plot. Should support vectorization.

• range (tuple[float, float]) – The range of the function(s). Will be plotted on the interval [range[0], range[1]].

• ax (matplotlib.axes.Axes) – The Axes instance for plotting.

• stacked (bool, optional) – Whether to use ax.stackplot() to plot the function(s) as a stacked plot. Default is False.

• npoints (int, optional) – The number of points to use for plotting. Default is 1000.

• **kwargs – Additional keyword arguments forwarded to ax.plot() (in case stacked=False) or ax.stackplot() (in case stacked=True).

Return type:

None

plothist.plotters.plot_hist(hist, ax, **kwargs)

Plot a histogram or a list of histograms from boost_histogram.

Parameters:

• hist (bh.Histogram | list[bh.Histogram]) – The histogram(s) to plot.

• ax (matplotlib.axes.Axes) – The Axes instance for plotting.

• **kwargs – Additional keyword arguments forwarded to ax.hist(), such as density, color, label, histtype…

Return type:

None

plothist.plotters.plot_hist_uncertainties(hist, ax, **kwargs)

Plot the symmetrical uncertainty, which is the Poisson standard deviation derived from the variance stored in the histogram, as a hatched area.

Parameters:

• hist (bh.Histogram) – The histogram from which we want to plot the uncertainties.

• ax (matplotlib.axes.Axes) – The Axes instance for plotting.

• **kwargs – Additional keyword arguments forwarded to ax.bar().

Return type:

None

plothist.plotters.plot_model(stacked_components=None, stacked_labels=None, stacked_colors=None, unstacked_components=None, unstacked_labels=None, unstacked_colors=None, xlabel=None, ylabel=None, stacked_kwargs=None, unstacked_kwargs_list=None, model_sum_kwargs=None, function_range=None, model_uncertainty=True, model_uncertainty_label='Model stat. unc.', fig=None, ax=None)

Plot model made of a collection of histograms.

Parameters:

• stacked_components (list[bh.Histogram] | None, optional) – The list of histograms to be stacked composing the model. Default is None.

• stacked_labels (list[str] | None, optional) – The labels of the model stacked components. Default is None.

• stacked_colors (list[str] | None, optional) – The colors of the model stacked components. Default is None.

• unstacked_components (list[bh.Histogram] | None, optional) – The list of histograms not to be stacked composing the model. Default is None.

• unstacked_labels (list[str] | list[None] | None, optional) – The labels of the model unstacked components. Default is None.

• unstacked_colors (list[str] | list[tuple[float, float, float]] | list[None] | None, optional) – The colors of the model unstacked components. Default is None.

• xlabel (str | None, optional) – The label for the x-axis. Default is None.

• ylabel (str | None, optional) – The label for the y-axis. Default is None.

• stacked_kwargs (dict[str, Any] | None, optional) – The keyword arguments used when plotting the stacked components in plot_hist() or plot_function(), one of which is called only once. Default is None.

• unstacked_kwargs_list (list[dict[str, Any]] | None, optional) – The list of keyword arguments used when plotting the unstacked components in plot_hist() or plot_function(), one of which is called once for each unstacked component. Default is None.

• model_sum_kwargs (dict[str, Any] | None, optional) – The keyword arguments for the plot_hist() function for the sum of the model components. Has no effect if all the model components are stacked or if the model is one unstacked element. The special keyword “show” can be used with a boolean to specify whether to show or not the sum of the model components. Default is None. If None is provided, this is set to {“show”: True, “label”: “Model”, “color”: “navy”}.

• function_range (tuple[float, float] | None, optional (mandatory if the model is made of functions)) – The range for the x-axis if the model is made of functions. Default is None.

• model_uncertainty (bool, optional) – If False, set the model uncertainties to zeros. Default is True.

• model_uncertainty_label (str, optional) – The label for the model uncertainties. Default is “Model stat. unc.”.

• fig (matplotlib.figure.Figure | None, optional) – The Figure object to use for the plot. If fig and ax are all None, a new figure will be created. Default is None.

• ax (matplotlib.axes.Axes | None, optional) – The Axes object to use for the plot. If fig and ax are all None, a new figure will be created. Default is None.

Returns:

• fig (matplotlib.figure.Figure) – The Figure object containing the plot.

• ax (matplotlib.axes.Axes) – The Axes object containing the plot.

Return type:

tuple[Figure, Axes]

plothist.plotters.plot_two_hist_comparison(h1, h2, xlabel=None, ylabel=None, h1_label='h1', h2_label='h2', fig=None, ax_main=None, ax_comparison=None, **comparison_kwargs)

Compare two histograms.

Parameters:

• h1 (bh.Histogram) – The first histogram to compare.

• h2 (bh.Histogram) – The second histogram to compare.

• xlabel (str | None, optional) – The label for the x-axis. Default is None.

• ylabel (str | None, optional) – The label for the y-axis. Default is None.

• h1_label (str, optional) – The label for the first histogram. Default is “h1”.

• h2_label (str, optional) – The label for the second histogram. Default is “h2”.

• fig (matplotlib.figure.Figure | None, optional) – The figure to use for the plot. If fig, ax_main and ax_comparison are all None, a new figure will be created. Default is None.

• ax_main (matplotlib.axes.Axes | None, optional) – The main axes for the histogram comparison. If fig, ax_main and ax_comparison are all None, a new figure will be created. Default is None.

• ax_comparison (matplotlib.axes.Axes | None, optional) – The axes for the comparison plot. If fig, ax_main and ax_comparison are all None, a new figure will be created. Default is None.

• **comparison_kwargs (optional) – Arguments to be passed to plot_comparison(), including the choice of the comparison function and the treatment of the uncertainties (see documentation of plot_comparison() for details).

Returns:

• fig (matplotlib.figure.Figure) – The created figure.

• ax_main (matplotlib.axes.Axes) – The main axes for the histogram comparison.

• ax_comparison (matplotlib.axes.Axes) – The axes for the comparison plot.

Return type:

tuple[Figure, Axes, Axes]

See also

plot_comparison

Plot the comparison between two histograms.

plothist.plotters.savefig(fig, path, new_figsize=None)

Save a Matplotlib figure with consistent figsize, axes size and subplot spacing (experimental feature).

Parameters:

• fig (matplotlib.figure.Figure) – The Matplotlib figure to be saved.

• path (str) – The output file path where the figure will be saved.

• new_figsize (tuple[float, float] | None, optional) – The new figsize as a (width, height) tuple. If None, the original figsize is preserved. Default is None.

Return type:

None

Comparison functions

plothist.comparison.get_asymmetrical_uncertainties(hist, uncertainty_type='asymmetrical')

Get Poisson asymmetrical uncertainties for a histogram via a frequentist approach based on a confidence-interval computation. Asymmetrical uncertainties can only be computed for an unweighted histogram, because the bin contents of a weighted histogram do not follow a Poisson distribution. More information in Notes on statistics.

Parameters:

• hist (bh.Histogram) – The histogram.

• uncertainty_type (str, optional) – The type of uncertainty to compute for bins with 0 entry. Default is “asymmetrical” (= “asymmetrical_one_sided_zeros”). Use “asymmetrical_double_sided_zeros” to have the double-sided definition. More information in Notes on statistics.

Returns:

• uncertainties_low (np.ndarray) – The lower uncertainties.

• uncertainties_high (np.ndarray) – The upper uncertainties.

Raises:

ValueError – If the histogram is weighted.

Return type:

tuple[ndarray, ndarray]

plothist.comparison.get_asymmetry(h1, h2)

Get the asymmetry between two histograms h1 and h2, defined as (h1 - h2) / (h1 + h2). Only symmetrical uncertainties are supported.

Parameters:

• h1 (bh.Histogram) – The first histogram.

• h2 (bh.Histogram) – The second histogram.

Returns:

• asymmetry_values (np.ndarray) – The asymmetry values.

• asymmetry_uncertainties (np.ndarray) – The uncertainties on the asymmetry.

Return type:

tuple[ndarray, ndarray]

plothist.comparison.get_comparison(h1, h2, comparison, h1_uncertainty_type='symmetrical')

Compute the comparison between two histograms.

Parameters:

• h1 (bh.Histogram) – The first histogram for comparison.

• h2 (bh.Histogram) – The second histogram for comparison.

• comparison (str) – The type of comparison (“ratio”, “split_ratio”, “pull”, “difference”, “relative_difference”, “efficiency”, or “asymmetry”). When the split_ratio option is used, the uncertainties of h1 are scaled down by the bin contents of h2, i.e. assuming zero uncertainty coming from h2 in the ratio uncertainty.

• h1_uncertainty_type (str, optional) – What kind of bin uncertainty to use for h1: “symmetrical” for the Poisson standard deviation derived from the variance stored in the histogram object, “asymmetrical” for asymmetrical uncertainties based on a Poisson confidence interval. Asymmetrical uncertainties are not supported for the asymmetry and efficiency comparisons. Default is “symmetrical”.

Returns:

• values (np.ndarray) – The comparison values.

• lower_uncertainties (np.ndarray) – The lower uncertainties on the comparison values.

• upper_uncertainties (np.ndarray) – The upper uncertainties on the comparison values.

Raises:

• ValueError – If the comparison is not valid.

• ValueError – If the h1_uncertainty_type is “asymmetrical” and the comparison is “asymmetry” or “efficiency”.

Return type:

tuple[ndarray, ndarray, ndarray]

plothist.comparison.get_difference(h1, h2, h1_uncertainty_type='symmetrical')

Compute the difference between two histograms.

Parameters:

• h1 (bh.Histogram) – The first histogram.

• h2 (bh.Histogram) – The second histogram.

• h1_uncertainty_type (str, optional) – What kind of bin uncertainty to use for h1: “symmetrical” for the Poisson standard deviation derived from the variance stored in the histogram object, “asymmetrical” for asymmetrical uncertainties based on a Poisson confidence interval. Default is “symmetrical”.

Returns:

• difference_values (np.ndarray) – The difference values.

• difference_uncertainties_low (np.ndarray) – The lower uncertainties on the difference.

• difference_uncertainties_high (np.ndarray) – The upper uncertainties on the difference.

Return type:

tuple[ndarray, ndarray, ndarray]

plothist.comparison.get_efficiency(h1, h2)

Calculate the ratio of two correlated histograms (h1/h2), in which the entries of h1 are a subsample of the entries of h2. The variances are calculated according to the formula given in Notes on statistics.

The following conditions must be fulfilled for the calculation of the efficiency: * The bins of the histograms must be equal. * The histograms must be unweighted. * The bin contents of both histograms must be positive or zero. * The bin contents of h1 must be a subsample of the bin contents of h2.

Parameters:

• h1 (bh.Histogram) – The first histogram.

• h2 (bh.Histogram) – The second histogram.

Returns:

• efficiency_values (np.ndarray) – The efficiency values.

• efficiency_uncertainties (np.ndarray) – The uncertainties on the efficiency values.

Raises:

• ValueError – If the histograms are weighted.

• ValueError – If the bin contents of the histograms are not positive or zero.

• ValueError – If the bin contents of h1 are not a subsample of the bin contents of h2.

Return type:

tuple[ndarray, ndarray]

plothist.comparison.get_pull(h1, h2, h1_uncertainty_type='symmetrical')

Compute the pull between two histograms.

Parameters:

• h1 (bh.Histogram) – The first histogram.

• h2 (bh.Histogram) – The second histogram.

• h1_uncertainty_type (str, optional) – What kind of bin uncertainty to use for h1: “symmetrical” for the Poisson standard deviation derived from the variance stored in the histogram object, “asymmetrical” for asymmetrical uncertainties based on a Poisson confidence interval. Default is “symmetrical”.

Returns:

• pull_values (np.ndarray) – The pull values.

• pull_uncertainties_low (np.ndarray) – The lower uncertainties on the pull. Always ones.

• pull_uncertainties_high (np.ndarray) – The upper uncertainties on the pull. Always ones.

Return type:

tuple[ndarray, ndarray, ndarray]

plothist.comparison.get_ratio(h1, h2, h1_uncertainty_type='symmetrical', ratio_uncertainty_type='uncorrelated')

Compute the ratio h1/h2 between two uncorrelated histograms h1 and h2.

Parameters:

• h1 (bh.Histogram) – The numerator histogram.

• h2 (bh.Histogram) – The denominator histogram.

• h1_uncertainty_type (str, optional) – What kind of bin uncertainty to use for h1: “symmetrical” for the Poisson standard deviation derived from the variance stored in the histogram object, “asymmetrical” for asymmetrical uncertainties based on a Poisson confidence interval. Default is “symmetrical”.

• ratio_uncertainty_type (str, optional) – How to treat the uncertainties of the histograms: * “uncorrelated” for the comparison of two uncorrelated histograms, * “split” for scaling down the uncertainties of h1 by bin contents of h2, i.e. assuming zero uncertainty coming from h2 in the ratio uncertainty. Default is “uncorrelated”.

Returns:

• ratio_values (np.ndarray) – The ratio values.

• ratio_uncertainties_low (np.ndarray) – The lower uncertainties on the ratio.

• ratio_uncertainties_high (np.ndarray) – The upper uncertainties on the ratio.

Raises:

ValueError – If the ratio_uncertainty_type is not valid.

Return type:

tuple[ndarray, ndarray, ndarray]

plothist.comparison.get_ratio_variances(h1, h2)

Calculate the variances of the ratio of two uncorrelated histograms (h1/h2).

Parameters:

• h1 (bh.Histogram) – The first histogram.

• h2 (bh.Histogram) – The second histogram.

Returns:

ratio_variances – The variances of the ratio of the two histograms.

Return type:

np.ndarray

Raises:

ValueError – If the bins of the histograms are not equal.

Variable registry functions

Collection of functions to manage the variable registry

plothist.variable_registry.create_variable_registry(variable_keys, path='./variable_registry.yaml', custom_dict=None, reset=False)

Create the variable registry yaml file given a list of variable keys. It stores all the plotting information for each variable.

It checks if the variable registry file exists. If not, it creates an empty file at the specified path. It then loads the existing variable registry, or creates an empty registry if it doesn’t exist. For each variable in the input list, if the variable is not already in the registry or the reset flag is True, it adds the variable to the registry with default settings. Finally, it writes the updated variable registry back to the file.

Default dictionary parameters of one variable in the yaml:

namestr

variable name in data.

binsint

Number of bins, default is 50.

range: tuple[float, float]

Range of the variables, default is [min, max] of the data.

labelstr

Label to display, default is variable name. Latex supported by surrounding the label with $label$.

logbool

True if plot in logscale, default is False

legend_locationstr

Default is best

legend_ncolsint

Default set to 1

docstringstr

Default is empty

Can also not use the default dictionary and provide a custom one using the ‘custom_dict’ parameter.

Parameters:

• variable_keys (list[str]) – A list of variable keys to be registered.

• path (str, optional) – The path to the variable registry file (default is “./variable_registry.yaml”).

• custom_dict (dict[str, Any], optional) – A dictionary containing the plotting information for the variables. Default dictionary is the one described above.

• reset (bool, optional) – If True, the registry will be reset to default values for all variable keys (default is False).

Return type:

None

plothist.variable_registry.get_variable_from_registry(variable_key, path='./variable_registry.yaml')

This function retrieves the parameter information for a variable from the variable registry file specified by the ‘path’ parameter. It loads the variable registry file and returns the dictionary entry corresponding to the specified variable name.

Parameters:

• variable_key (str) – The name of the variable for which to retrieve parameter information.

• path (str, optional) – The path to the variable registry file (default is “./variable_registry.yaml”).

Returns:

A dictionary containing the parameter information for the specified variable.

Return type:

dict[str, Any]

See also

create_variable_registry

plothist.variable_registry.remove_variable_registry_parameters(parameters, variable_keys=None, path='./variable_registry.yaml')

Remove the specified parameters from the variable registry file.

Parameters:

• parameters (list[str]) – A list of parameters to remove from the variable keys.

• variable_keys (list[str]) – A list of variable keys for which to remove the specified parameters from the registry. Default is None: all variables in the registry are updated.

• path (str, optional) – The path to the variable registry file (default is “./variable_registry.yaml”).

Return type:

None

plothist.variable_registry.update_variable_registry(dictionary, variable_keys=None, path='./variable_registry.yaml', overwrite=False)

Update the variable registry file with a dictionary. Each key in the provided dictionary will be added as parameters for each variable. If they are already in the variable information, they will be updated with the new values only if the overwrite flag is True.

Parameters:

• dictionary (dict[str, Any]) – A dictionary containing the information to update the registry with.

• variable_keys (list[str]) – A list of variable keys for which to update the registry. Default is None: all variables in the registry are updated.

• path (str, optional) – The path to the variable registry file (default is “./variable_registry.yaml”).

• overwrite (bool, optional) – If True, the keys will be overwritten by the provided value in the dictionary (default is False).

Return type:

None

plothist.variable_registry.update_variable_registry_binning(data, variable_keys=None, path='./variable_registry.yaml', overwrite=False)

Update both the bins and range parameters for multiple variables in the variable registry file.

Parameters:

• data (numpy.ndarray or pandas.DataFrame) – A dataset containing the data for the variables.

• variable_keys (list[str]) – A list of variable keys for which to update the parameters in the registry. The variable needs to have a bin and range properties in the registry. Default is None: all variables in the registry are updated.

• path (str, optional) – The path to the variable registry file (default is “./variable_registry.yaml”).

• overwrite (bool, optional) – If True, the bin and range parameters will be overwritten even if they differ from “auto” and (“min”, “max”) (default is False).

Return type:

None

Raises:

RuntimeError – If the variable does not have a name, bins or range property in the registry.

Plotting style functions

plothist.plothist_style.add_luminosity(collaboration, x='right', y='top', fontsize=12, is_data=True, lumi='', lumi_unit='fb', preliminary=False, two_lines=False, white_background=False, ax=None, **kwargs)

Add the collaboration name and the integrated luminosity (or “Simulation”).

Parameters:

• collaboration (str) – Collaboration name.

• x (float | str, optional) – Horizontal position of the text in unit of the normalized x-axis length. The default is value “right”, which is an alias for 1.0. Can take other aliases such as “left”, “left_in”, “right_in”, “right_out”.

• y (float | str, optional) – Vertical position of the text in unit of the normalized y-axis length. The default is value “top”, which is an alias for 1.01. Can take other aliases such as “top_in”, “bottom_in”, “top_out”=”top”, “bottom_out”=”bottom”.

• fontsize (int, optional) – Font size, by default 12.

• is_data (bool, optional) – If True, plot integrated luminosity. If False, plot “Simulation”, by default True.

• lumi (int | str, optional) – Integrated luminosity. If empty, do not plot luminosity. Default value is empty.

• lumi_unit (str, optional) – Integrated luminosity unit. Default value is fb. The exponent is automatically -1.

• preliminary (bool, optional) – If True, print “preliminary”, by default False.

• two_lines (bool, optional) – If True, write the information on two lines, by default False.

• white_background (bool, optional) – Draw a white rectangle under the text, by default False.

• ax (matplotlib.axes.Axes, optional) – Figure axis, by default None.

• kwargs (dict[str, Any]) – Keyword arguments to be passed to the ax.text() function. In particular, the keyword arguments ha and va, which are set to “left” (or “right” if x=”right”) and “bottom” by default, can be used to change the text alignment.

Return type:

None

See also

add_text

Add information on the plot.

plothist.plothist_style.add_text(text, x='left', y='top', fontsize=12, white_background=False, ax=None, **kwargs)

Add text to an axis.

Parameters:

• text (str) – The text to add.

• x (float | str, optional) – Horizontal position of the text in unit of the normalized x-axis length. The default is value “left”, which is an alias for 0.0. Other aliases are “right”, “left_in”, “right_in”, “right_out”.

• y (float | str, optional) – Vertical position of the text in unit of the normalized y-axis length. The default is value “top”, which is an alias for 1.01. Other aliases are “top_in”, “bottom_in”, “top_out”=”top”, “bottom_out”=”bottom”.

• fontsize (int, optional) – Font size, by default 12.

• white_background (bool, optional) – Draw a white rectangle under the text, by default False.

• ax (matplotlib.axes.Axes, optional) – Figure axis, by default None.

• kwargs (dict[str, Any]) – Keyword arguments to be passed to the ax.text() function. In particular, the keyword arguments ha and va, which are set by default to accommodate to the x and y aliases, can be used to change the text alignment.

Raises:

ValueError – If the x or y position is not a float or a valid position.

Return type:

None

plothist.plothist_style.cubehelix_palette(ncolors=7, start=1.5, rotation=1.5, gamma=1.0, hue=0.8, lightest=0.8, darkest=0.3, reverse=True)

Make a sequential palette from the cubehelix system, in which the perceived brightness is linearly increasing. This code is adapted from seaborn, which implements equation (2) of reference [1] below.

Parameters:

• ncolors (int, optional) – Number of colors in the palette.

• start (float, 0 <= start <= 3, optional) – Direction of the predominant colour deviation from black at the start of the colour scheme (1=red, 2=green, 3=blue).

• rotation (float, optional) – Number of rotations around the hue wheel over the range of the palette.

• gamma (float, 0 <= gamma, optional) – Gamma factor to emphasize darker (gamma < 1) or lighter (gamma > 1) colors.

• hue (float, 0 <= hue <= 1, optional) – Saturation of the colors.

• darkest (float, 0 <= darkest <= 1, optional) – Intensity of the darkest color in the palette.

• lightest (float, 0 <= lightest <= 1, optional) – Intensity of the lightest color in the palette.

• reverse (bool, optional) – If True, the palette will go from dark to light.

Returns:

The generated palette of colors represented as a list of RGB tuples.

Return type:

list[tuple[float, float, float]]

References

[1] Green, D. A. (2011). “A colour scheme for the display of astronomical intensity images”. Bulletin of the Astromical Society of India, Vol. 39, p. 289-295.

plothist.plothist_style.get_color_palette(cmap, N)

Get N different colors from a chosen colormap.

Parameters:

• cmap (str) – The name of the colormap to use. Use “ggplot” get the cycle of the plothist style. Use “cubehelix” to get the cubehelix palette with default settings. Can also be any colormap from matplotlib (we recommend “viridis”, “coolwarm” or “YlGnBu_r”).

• N (int) – The number of colors to sample.

Returns:

A list of colors. If “ggplot” is selected, returns a list of hex color strings. Otherwise, returns a list of RGB color tuples.

Return type:

list[str] or list[tuple[float, float, float]]

References

ggplot colormap: https://matplotlib.org/stable/gallery/style_sheets/ggplot.html Matplotlib colormaps: https://matplotlib.org/stable/gallery/color/colormap_reference.html

See also

cubehelix_palette

Make a sequential palette from the cubehelix system.

plothist.plothist_style.plot_reordered_legend(ax, order, **kwargs)

Reorder the legend handlers and labels on the given Matplotlib axis based on the specified order and plot the reordered legend.

Parameters:

• ax (matplotlib.axes.Axes) – The Matplotlib Axes object on which the legend is to be reordered.

• order (list[int]) – A list of integers specifying the new order of the legend items. The integers refer to the indices of the current legend items.

• kwargs (dict[str, Any], optional) – Keyword arguments to be passed to the ax.legend() function, such as the legend location (loc).

Return type:

None

Raises:

ValueError – If the order list does not contain all integers from 0 to len(labels) - 1.

Examples

>>> fig, ax = plt.subplots()
>>> ax.plot([1, 2, 3], label='Line 1')
>>> ax.plot([3, 2, 1], label='Line 2')

To reorder the legend so that ‘Line 2’ comes first, use:

>>> plot_reordered_legend(ax, [1, 0])

plothist.plothist_style.set_fitting_ylabel_fontsize(ax)

Get the suitable font size for a ylabel text that fits within the plot’s y-axis limits.

Parameters:

ax (matplotlib.axes.Axes) – The matplotlib subplot to adjust the ylabel font size for.

Returns:

The adjusted font size for the ylabel text.

Return type:

float

plothist.plothist_style.set_style(style='default')

Set the plothist style.

Parameters:

style (str, optional) – Switch between different styles. Default is ‘default’. More style might come in the future.

Return type:

None

Raises:

ValueError – If the specified style is not in the available styles.

Notes

• The default plothist style is tuned to be presentation and publication ready.