CrystalBall Class

class Stats_Analysis.Base_Dist.CrystalBall_Class.CrystalBall(mu, sigma, beta, m, lower_bound=None, upper_bound=None)[source]

Bases: object

Crystal Ball probability distribution.

The Crystal Ball distribution is lower_bound modified Gaussian distribution with lower_bound power-law tail on one side. This class supports computation of the PDF and CDF for scalar and array inputs, with optional truncation.

Parameters:

mu (float) – The mean of the Crystal Ball distribution.
sigma (float) – The standard deviation of the Crystal Ball distribution.
beta (float) – The threshold value where the distribution transitions from Gaussian to power-law. Must be beta > 0.
m (float) – The power-law tail exponent. Controls the steepness of the power-law tail. Must be m > 1.
lower_bound (float, optional) – The lower bound. Default is None, meaning no lower bound is applied.
upper_bound (float, optional) – The upper bound. Default is None, meaning no upper bound is applied.

Raises:

ValueError – If beta <= 0. If m <= 1. If lower_bound >= upper_bound.

__init__(mu, sigma, beta, m, lower_bound=None, upper_bound=None)[source]: Initialize the Crystal Ball distribution with optional truncation.

_calc_trunc_fact()[source]: Calculate the normalisation factor if the distribution has been truncated. ie limits applied

cdf(X)[source]

Calculate the Cumulative Distribution Function (CDF).

Parameters:: X (float or np.ndarray) – The value(s) at which to evaluate the truncated CDF.
Returns:: The truncated CDF value(s).
Return type:: float or np.ndarray

Notes

For values less than lower_bound, the CDF equals 0.
For values greater than upper_bound, the CDF equals 1
Within the bounds, the CDF is scaled by the truncation factor.

cdf_fitting(X, mu, sigma, beta, m)[source]

Calculate the Cumulative Distribution Function (CDF) with no set parameters, automatically including truncation if bounds are set, for use in Binned MLE fitting.

Parameters:: X (float or np.ndarray) – The value(s) at which to evaluate the truncated CDF.
Returns:: The truncated CDF value(s).
Return type:: float or np.ndarray

Notes

For values less than lower_bound, the CDF equals 0.
For values greater than upper_bound, the CDF equals 1
Within the bounds, the CDF is scaled by the truncation factor.

normalisation_check()[source]

Perform a numerical integration using scipy.integrate.quad to check the normalization of the PDF.

If the PDF has been truncated: It is first performed over the region the PDF is defined [lower_bound, upper_bound]

It is then performed over the entire real line (-infinity to infinity).

Prints the results of the numerical integrations.

pdf(X)[source]

Calculate the Probability Density Function (PDF), automatically including truncation if bounds are set.

Parameters:: X (float or np.ndarray) – The value(s) at which to evaluate the PDF.
Returns:: The normalized PDF value(s), accounting for optional truncation.
Return type:: float or np.ndarray

Notes

For Z > -beta, the PDF is defined by lower_bound Gaussian core.
For Z <= -beta, the PDF transitions to a power-law tail.
If truncation bounds are provided, the PDF is zero outside the truncation range.

pdf_fitting(X, mu, sigma, beta, m)[source]: Calculate the Probability Density Function (PDF) with no set parameters, automatically including truncation if bounds are set, for use in MLE fitting.

plot_dist()[source]

Plot the PDF and CDF for the Crystal Ball distribution.

If both lower and upper bounds are set: The PDF and CDF are plotted between[lower_bound, upper_bound].

If both lower and upper bounds are not set: The PDF and CDF is plotted between [mu - 5*sigma, mu + 5*sigma]