Mathematical utilities — `pygama.math`¶

The pygama.math sub-package provides the statistical infrastructure used throughout pygama: histogram helpers, probability distributions, and fitting routines. It is designed to be usable independently of the rest of the processing chain for ad-hoc data analysis.

Overview¶

pygama.math is organised around three concerns:

Histogramming — convenience wrappers around boost-histogram that return the (hist, bins, var) triple expected by the fitting routines.
Distributions — a library of probability density functions (PDFs) and cumulative distribution functions (CDFs) that model the signal and background shapes encountered in HPGe detector data. All functions are JIT-compiled with Numba for speed and are compatible with iminuit.
Fitting — thin wrappers around iminuit that expose a consistent interface for binned and unbinned maximum-likelihood fits, including goodness-of-fit statistics and uncertainty estimation.

Submodules¶

histogram¶

pygama.math.histogram provides convenience functions for working with one-dimensional histograms. All functions operate on the standard pygama histogram triple (hist, bins, var):

hist — array of bin counts (or weighted counts).
bins — array of bin edges, length len(hist) + 1.
var — array of per-bin variances; defaults to hist (Poisson statistics) if not supplied.

Function	Description
`get_hist()`	Bin a 1-D array of data values, returning `(hist, bins, var)`. Accepts a fixed bin count, an explicit array of edges, a bin-width `dx`, or any string accepted by `numpy.histogram_bin_edges`.
`get_fwhm()`	Compute the full-width at half-maximum (FWHM) of a histogram peak.
`get_fwfm()`	Compute the full-width at a given fraction of the maximum (FWFM).
`get_i_local_maxima()`	Return the indices of local maxima above a threshold, used for automatic peak finding.
`get_bin_estimates()`	Evaluate a normalised PDF on a histogram grid for use in plotting.
`plot_hist()`	Plot a histogram triple on a Matplotlib axes object.

distributions¶

pygama.math.distributions re-exports all distribution objects defined in the pygama.math.functions sub-package. Each distribution is a PygamaContinuous instance (a subclass of scipy.stats.rv_continuous) with Numba-compiled PDF and CDF methods.

Composite distributions — a signal peak plus a background model — are the most commonly used in HPGe peak fitting:

Distribution	Description
`hpge_peak`	Full HPGe peak model: a Gaussian signal component convolved with a low-energy tail (exGaussian), sitting on a step-function background with a linear slope. The standard model for fitting calibration peaks.
`gauss_on_step`	Gaussian signal on a step-function background.
`gauss_on_linear`	Gaussian signal on a linear background.
`gauss_on_exponential`	Gaussian signal on an exponential background.
`gauss_on_exgauss`	Gaussian signal on an exGaussian background.
`gauss_on_uniform`	Gaussian signal on a uniform background.
`triple_gauss_on_double_step`	Three Gaussian components on a double step background; used for complex multi-peak regions.

Primitive distributions:

Distribution	Description
`gaussian`	Normal (Gaussian) distribution.
`exgauss`	Exponentially modified Gaussian; models the low-energy tail of HPGe peaks due to incomplete charge collection.
`crystal_ball`	Crystal Ball function; a Gaussian with a power-law low-energy tail.
`step`	Step (Heaviside-convolved-with-Gaussian) background.
`exponential`	Exponential background.
`linear`	Linear background.
`uniform`	Uniform (flat) distribution.
`moyal`	Moyal distribution; approximates the Landau distribution for energy-loss processes.
`nb_poly`	Polynomial of arbitrary degree.

binned_fitting¶

pygama.math.binned_fitting provides a unified interface for fitting a function to a histogram triple. The default cost function is an extended binned log-likelihood fit (iminuit.cost.ExtendedBinnedNLL).

Function	Description
`fit_binned()`	Fit a model to a histogram triple; returns best-fit parameter values, uncertainties, and optionally the full `Minuit` object.
`goodness_of_fit()`	Compute a reduced chi-squared statistic and p-value for a fit result.
`gauss_mode_width_max()`	Fit a Gaussian to a histogram peak and return the mode, width, and maximum, useful for robust initial-parameter estimation.

unbinned_fitting¶

pygama.math.unbinned_fitting provides the unbinned counterpart to binned_fitting. The default cost function is the extended unbinned negative log-likelihood (iminuit.cost.ExtendedUnbinnedNLL).

Unbinned fits are preferred when the dataset is small (fewer than a few thousand events) or when the bin-size choice would significantly affect the result.

Function	Description
`fit_unbinned()`	Fit a model to an array of unbinned data values using extended unbinned negative log-likelihood minimisation.

hpge_peak_fitting¶

pygama.math.hpge_peak_fitting contains higher-level routines that combine the distribution and fitting machinery to fit the standard HPGe peak model (hpge_peak) to data, with automatic initial-parameter estimation.

Function	Description
`hpge_peak_fwhm()`	Compute the FWHM of an HPGe peak from the fit parameters, propagating uncertainties analytically.
`hpge_peak_fwfm()`	Compute the full-width at a given fraction of the maximum.
`hpge_peak_mode()`	Return the mode (peak position) of the HPGe peak model.

least_squares¶

pygama.math.least_squares provides simple linear least-squares helpers used internally by pygama.pargen.energy_cal.

units¶

pygama.math.units exposes the unit registry (backed by pint) and a small set of unit-conversion helpers.

For the complete parameter reference see pygama.math.

Mathematical utilities — pygama.math¶