hist — Histograms#

The module provides an abstract base class for n-dimensional histograms along with concrete implementations for 1D and 2D histograms:

  • AbstractHistogram: Abstract base class for histograms;

  • Histogram1d: 1D histogram implementation;

  • Histogram2d: 2D histogram implementation.

Histograms are constructed with the bin edges (and, optionally, labels to be used at the plotting stage) and are filled using the fill() method. The basic semantics is as follows:

import numpy as np
from aptapy.hist import Histogram1d, Histogram2d

rng = np.random.default_rng()
edges = np.linspace(-5., 5., 100)

hist = Histogram1d(edges, "x")
hist.fill(rng.normal(size=1000))
hist.plot()

hist = Histogram2d(edges, edges, 'x', 'y')
hist.fill(rng.normal(size=1000), rng.normal(size=1000))
hist.plot()

Histograms support weighted filling and basic arithmetic operations (addition and subtraction) between histograms with identical binning.

Warning

Multiplication by a scalar is not yet supported.

See also

Have a look at the Simple 1-D histogram, Simple 2-D histogram and Weighted 1-D histogram examples.

Module documentation#

Histogram facilities.

class aptapy.hist.Histogram1d(xedges: ndarray, label: str = None, xlabel: str = None, ylabel: str = 'Entries/bin')[source]#

One-dimensional histogram.

Arguments#

edges1-dimensional array

the bin edges.

labelstr

overall label for the histogram (if defined, this will be used in the legend by default).

xlabelstr

the text label for the x axis.

ylabelstr

the text label for the y axis (default: “Entries/bin”).

DEFAULT_PLOT_OPTIONS = {'alpha': 0.4, 'histtype': 'stepfilled'}#
_projection_hist_class()[source]#

Overloaded method.

classmethod from_amptek_file(file_path: str | Path) → Histogram1d[source]#

Return a Histogram1d filled with ADC counts from a file acquired with the Amptek MCA8000A Multichannel Analyzer, see https://www.amptek.com/internal-products/mca8000a-multichannel-analyzer-software-downloads

Arguments#

file_pathPathLike

The path of the file to read.

Returns#

Histogram1d

A Histogram1d object with bins corresponding to ADC channels and filled with the counts from the file.

area() → float[source]#

Return the total area under the histogram.

This is potentially useful when fitting a model to the histogram, e.g., to freeze the prefactor of a gaussian to the histogram normalization.

Returns#

areafloat

The total area under the histogram.

fwhm() → float[source]#

Return the full width at half maximum (FWHM) of the histogram.

If the distribution is not well behaved (e.g., the maximum is at the edge or it is flat), a ValueError is raised.

Returns#

fwhmfloat

The full width at half maximum of the histogram.

_normalized_cumsum() → ndarray[source]#

Return the normalized cumulative sum of the histogram contents.

Returns#

cumsumnp.ndarray

the normalized cumulative sum of the histogram contents.

cdf(x: float | ndarray) → float | ndarray[source]#

Evaluate the cumulative distribution function (CDF) of the histogram at the specified values.

Internally we are using a PCHIP interpolation to avoid oscillations and preserve monotonicity. Note we are deliberately not making the creation of the interpolator a cached property (which is only supported in Python 3.8+, by the way) as the histogram content might change after the each call, and we want to always have the up-to-date CDF.

Arguments#

xArrayLike

the values where to evaluate the cdf.

Returns#

cdfArrayLike

the cumulative distribution function (CDF) of the histogram evaluated at x.

ppf(x: float | ndarray) → float | ndarray[source]#

Evaluate the percent point function (PPF) of the histogram at the specified values.

The PPF is calculated by interpolating the inverse of the cumulative sums of the histogram contents.

Note that the PPF is only defined in the [0, 1] domain. For values outside this range, NaN is returned. The same notes about the CDF interpolation apply here, namely: internally we are using a PCHIP interpolation to avoid oscillations and preserve monotonicity. We are deliberately not making the creation of the interpolator a cached property (which is only supported in Python 3.8+, by the way) as the histogram content might change after the each call, and we want to always have the up-to-date PPF.

Arguments#

xArrayLike

the values where to evaluate the ppf.

Returns#

ppfArrayLike

the percent point function (PPF) of the histogram evaluated at x.

_coverage_interval(x: float | ndarray, coverage: float) → float | ndarray[source]#

Calculate the coverage interval width, given the lower edge of the interval.

Arguments#

xArrayLike

the lower edges where to calculate the interval widths.

coveragefloat

the coverage of the interval

Returns#

deltaArrayLike

the widths of the interval

minimum_coverage_interval(coverage: float) → Tuple[float, float][source]#

Calculate the minimum coverage interval of the histogram for a given coverage.

Arguments#

coveragefloat

the coverage of the interval

Returns#

xmin, xmaxTuple[float, float]

the left and right edges of the minimum coverage interval.

plot(axes: Axes = None, statistics: bool = False, errors: bool = False, **kwargs) → None[source]#

Overloaded plot() method.

This method adds an option to include basic statistics (mean and RMS) in the legend entry. Note that, apart from this addition, the method behaves as the base class dictates.

Arguments#

axesmatplotlib.axes.Axes, optional

the axes where to plot the histogram (default: current axes).

statisticsbool, optional

whether to include basic statistics (mean and RMS) in the legend entry (default: False).

errorsbool, optional

whether to overplot the error bars (default: False).

kwargskeyword arguments

additional keyword arguments passed to the plotting backend.

_render(axes: Axes, **kwargs) → None[source]#

Overloaded method.

_render_errors(axes: Axes, **kwargs) → None[source]#

Small convenience function to overplot the error bars on the histogram.

_abc_impl = <_abc._abc_data object>#
class aptapy.hist.Histogram2d(xedges, yedges, label: str = None, xlabel: str = None, ylabel: str = None, zlabel: str = 'Entries/bin')[source]#

Two-dimensional histogram.

Arguments#

xedges1-dimensional array

the bin edges on the x axis.

yedges1-dimensional array

the bin edges on the y axis.

labelstr

overall label for the histogram

xlabelstr

the text label for the x axis.

ylabelstr

the text label for the y axis.

zlabelstr

the text label for the z axis (default: “Entries/bin”).

DEFAULT_PLOT_OPTIONS = {'cmap': <matplotlib.colors.LinearSegmentedColormap object>}#
_projection_hist_class()[source]#

Overloaded method.

_render(axes: Axes, logz: bool = False, **kwargs) → None[source]#

Overloaded method.

_abc_impl = <_abc._abc_data object>#
class aptapy.hist.Histogram3d(xedges, yedges, zedges, label: str = None, xlabel: str = None, ylabel: str = None, zlabel: str = None)[source]#

Three-dimensional histogram.

Arguments#

xedges1-dimensional array

the bin edges on the x axis.

yedges1-dimensional array

the bin edges on the y axis.

zedges1-dimensional array

the bin edges on the z axis.

labelstr

overall label for the histogram

xlabelstr

the text label for the x axis.

ylabelstr

the text label for the y axis.

zlabelstr

the text label for the z axis (default: None).

_projection_hist_class()[source]#

Overloaded method.

_render(axes: Axes, **kwargs) → None[source]#

Overloaded method.

Note that 3D histograms cannot be directly plotted, so we just raise a NotImplementedError.

_abc_impl = <_abc._abc_data object>#