pelutils.stats package

Statistical helpers and SciPy distributions parametrised the way textbooks are.

scipy.stats parametrises every distribution through generic loc/scale arguments, which rarely match how a distribution is actually defined: an exponential’s scale is 1 / lambda, a normal takes a standard deviation rather than a variance, and a gamma’s a/scale bear no obvious relation to its shape and rate. This module wraps the SciPy distributions so you pass their natural parameters instead — following the conventions in Jim Pitman’s Probability — and returns an ordinary frozen SciPy distribution, so .pdf, .cdf, .rvs and friends all work as usual. It also provides z_score() for turning a significance level into a critical value.

Quick start

from pelutils.stats import expon, norm, z_score

dist = norm(mu=0, sigma2=4)   # mean and *variance*, not standard deviation
dist.cdf(1.5)                 # a plain frozen SciPy distribution

# 95 % confidence-interval half-width for a standard normal
half_width = z_score()        # standard deviation is 1

# Upper 1 % critical value for an Exponential(lambda=2)
zval = z_score(alpha=0.01, two_sided=False, distribution=expon(lambda_=2))

Continuous distributions: norm(), lognorm(), expon(), gamma(), chi2(), rayleigh(), beta(). Discrete distributions: bernoulli(), binomial(), poisson(), hypergeom(), geom0(), geom1(), nbinom().

pelutils.stats.bernoulli(p: float)

Return a Bernoulli distribution with success probability p.

pelutils.stats.beta(r: float, s: float)

Return a beta distribution.

pelutils.stats.binomial(n: int, p: float)

Return a binomial distribution for n trials with success probability p.

pelutils.stats.chi2(n: int | float)

Return a chi-squared distribution with the given number of degrees of freedom.

Although degrees of freedom are commonly given as an integer, the distribution is here represented as a special case of the gamma distribution, making it defined for any positive real n.

pelutils.stats.expon(lambda_: float)

Return an exponential distribution with rate lambda_ and mean 1 / lambda_.

pelutils.stats.gamma(r: float, lambda_: float)

Return a gamma distribution with shape r and rate lambda_.

pelutils.stats.geom0(p: float)

Return a geometric distribution of failures before the first success, with success probability p.

pelutils.stats.geom1(p: float)

Return a geometric distribution of the trial of the first success, with success probability p.

pelutils.stats.hypergeom(n: int, N: int, G: int)

Return a hypergeometric distribution.

Parameters:

• n – Number of items drawn from the population.

• N – Population size.

• G – Number of successes in the population.

pelutils.stats.lognorm(mu: float, sigma2: float)

Return a log-normal distribution where log(X) has mean mu and variance sigma2.

pelutils.stats.nbinom(r: int, p: float)

Return a negative binomial distribution of failures before r successes, with success probability p.

pelutils.stats.norm(mu: float, sigma2: float)

Return a normal distribution with mean mu and variance sigma2.

pelutils.stats.poisson(mu: float)

Return a Poisson distribution with mean and rate mu.

pelutils.stats.rayleigh()

Return a Rayleigh distribution.

pelutils.stats.z_score(alpha: float = 0.05, two_sided: bool = True, distribution: Any | None = None) → float

Return an upper critical value for a given significance level.

Parameters:

• alpha (float, optional) – Significance level in [0, 1].

• two_sided (bool, optional) – If True, use an upper-tail probability of alpha / 2; otherwise use alpha. For symmetric distributions this gives the usual two-sided cutoff for a distribution symmetric about zero, with the lower cutoff equal to the negative of the returned value. For asymmetric distributions, the returned value is only the upper cutoff.

• distribution (Any | None, optional) – A frozen SciPy distribution to draw the quantile from. Defaults to N(0, 1), in which case the two-sided default returns the familiar ~1.96.