mixle.stats.univariate.discrete.beta_binomial module¶

Beta-binomial distribution – an overdispersed binomial (Beta-binomial compound).

If the success probability of a binomial is itself Beta(a, b) distributed and integrated out, the count k in n trials follows the beta-binomial:

P(k; n, a, b) = C(n, k) B(k + a, n - k + b) / B(a, b), k = 0, …, n,

with mean n a/(a+b) and a variance inflated over the binomial by the intra-class correlation rho = 1/(a+b+1). It is the standard model for overdispersed bounded counts (clustered trials, batch defect rates). The number of trials n is a fixed, known parameter; a and b are estimated by moments – rho from the dispersion and the mean fixing a/(a+b).

class BetaBinomialDistribution(n, a, b, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Beta-binomial distribution over {0, ..., n} with shape parameters a, b > 0.

Parameters:

n (int)
a (float)
b (float)
name (str | None)
keys (str | None)

density(x)[source]

Return the probability mass at a single count x.

Parameters:: x (int)
Return type:: float

log_density(x)[source]

Return the log probability mass at x (-inf outside {0, ..., n} or non-integer – a fractional count is not a valid beta-binomial outcome).

Parameters:: x (int)
Return type:: float

seq_log_density(x)[source]

Return vectorized log-mass for an array of counts (-inf outside {0, ..., n} or non-integer – a fractional count is not a valid beta-binomial outcome).

Parameters:: x (ndarray)
Return type:: ndarray

support_size()[source]

n + 1 outcomes {0, ..., n}.

Return type:: int

cdf(x)[source]

Cumulative distribution function P(X <= x): a log-space partial sum of the pmf over {0..n}.

Parameters:: x (float)
Return type:: float

quantile(q)[source]

Inverse CDF F^{-1}(q) over {0..n}: the smallest count whose cdf reaches q (search on the cdf).

Parameters:: q (float)
Return type:: float

enumerator()[source]

Returns BetaBinomialEnumerator iterating the support in descending probability order.

Return type:: BetaBinomialEnumerator

sampler(seed=None)[source]

Return a sampler for drawing counts from this distribution.

Parameters:: seed (int | None)
Return type:: BetaBinomialSampler

estimator(pseudo_count=None)[source]

Return a method-of-moments estimator for a, b at the fixed number of trials n.

Parameters:: pseudo_count (float | None)
Return type:: BetaBinomialEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:: BetaBinomialDataEncoder

class BetaBinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate the bounded beta-binomial support {0, …, n} in descending probability order.

Unlike the binomial, the beta-binomial pmf is not always unimodal (it is U-shaped for a < 1, b < 1), so a two-pointer walk from a mode is not safe here; the finite support is materialized and sorted instead (the CategoricalEnumerator pattern), with value-order tie-breaks.

Parameters:: dist (BetaBinomialDistribution)

class BetaBinomialSampler(dist, seed=None)[source]

Bases: DistributionSampler

Draw counts as p ~ Beta(a, b) then k ~ Binomial(n, p).

Parameters:

dist (BetaBinomialDistribution)
seed (int | None)

sample(size=None, *, batched=True)[source]

Draw one count or an array of iid counts.

Parameters:

size (int | None)
batched (bool)

Return type:

int | ndarray

class BetaBinomialAccumulator(n, name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted first and second moments for beta-binomial estimation.

Parameters:

n (int)
name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Accumulate weighted first and second moments for one count.

Parameters:

x (int)
weight (float)
estimate (BetaBinomialDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]

Initialize statistics from one count.

Parameters:

x (int)
weight (float)
rng (RandomState | None)

Return type:

None

supported_rows(x)[source]

Encoded rows this law can be fitted on: counts in {0, ..., n}.

The encoder admits a count outside that range so a mixture can encode one batch against every component (P02-F03); this is the predicate that keeps it out of the moments and the one a latent model’s initialization consults before handing this component any responsibility (Q01-F02).

Return type:: ndarray

seq_update(x, weights, estimate)[source]

Accumulate weighted moments from encoded counts.

A count outside {0, ..., n} carrying weight is refused; with zero weight it contributes nothing.

Parameters:

x (ndarray)
weights (ndarray)
estimate (BetaBinomialDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize statistics from encoded counts.

Parameters:

x (ndarray)
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Merge another beta-binomial sufficient-statistic tuple.

Parameters:: suff_stat (tuple[float, float, float])
Return type:: BetaBinomialAccumulator

value()[source]

Return accumulated sum, second moment sum, and count.

Return type:: tuple[float, float, float]

from_value(x)[source]

Replace accumulator contents from a sufficient-statistic tuple.

Parameters:: x (tuple[float, float, float])
Return type:: BetaBinomialAccumulator

acc_to_encoder()[source]

Return the encoder used by this accumulator.

Return type:: BetaBinomialDataEncoder

class BetaBinomialAccumulatorFactory(n, name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for BetaBinomialAccumulator.

Parameters:

n (int)
name (str | None)
keys (str | None)

make()[source]

Create a fresh beta-binomial accumulator.

Return type:: BetaBinomialAccumulator

class BetaBinomialEstimator(n, pseudo_count=None, suff_stat=None, min_conc=1.0e-6, max_conc=1.0e8, name=None, keys=None)[source]

Bases: ParameterEstimator

Method-of-moments estimator for the beta-binomial shape parameters.

Parameters:

n (int)
pseudo_count (float | None)
suff_stat (tuple[float, float] | None)
min_conc (float)
max_conc (float)
name (str | None)
keys (str | None)

accumulator_factory()[source]

Return an accumulator factory for beta-binomial moments.

Return type:: BetaBinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate beta-binomial shape parameters from weighted moments.

Parameters:

nobs (float | None)
suff_stat (tuple[float, float, float])

Return type:

BetaBinomialDistribution

class BetaBinomialDataEncoder(n)[source]

Bases: DataSequenceEncoder

Encode beta-binomial counts as a float array.

Parameters:: n (int)

seq_encode(x)[source]

Encode exact counts, admitting counts outside the support {0, ..., n}.

Being an exact integer is a type contract and stays enforced; being inside {0, ..., n} is a probability question the scorer answers -inf, so a mixture whose other component owns such a count can encode the whole batch (P02-F03, Q01-F02).

Parameters:: x (Sequence[int])
Return type:: ndarray