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:
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}).

Parameters:

x (int)

Return type:

float

seq_log_density(x)[source]

Return vectorized log-mass for an array of counts.

Parameters:

x (ndarray)

Return type:

ndarray

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 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)[source]

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

Parameters:

size (int | None)

Return type:

int | ndarray

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

Bases: SequenceEncodableStatisticAccumulator

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

Parameters:

  • name (str | None)

  • keys (str | None)

update(x, weight, estimate)[source]
Parameters:

  • x (int)

  • weight (float)

  • estimate (BetaBinomialDistribution | None)

Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]
Parameters:

  • x (ndarray)

  • weights (ndarray)

  • estimate (BetaBinomialDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

combine(suff_stat)[source]
Parameters:

suff_stat (tuple[float, float, float])

Return type:

BetaBinomialAccumulator

value()[source]
Return type:

tuple[float, float, float]

from_value(x)[source]
Parameters:

x (tuple[float, float, float])

Return type:

BetaBinomialAccumulator

key_merge(stats_dict)[source]

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]
Return type:

BetaBinomialDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for BetaBinomialAccumulator.

Parameters:

  • name (str | None)

  • keys (str | None)

make()[source]
Return type:

BetaBinomialAccumulator

class BetaBinomialEstimator(n, 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:
accumulator_factory()[source]
Return type:

BetaBinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
Return type:

BetaBinomialDistribution

class BetaBinomialDataEncoder[source]

Bases: DataSequenceEncoder

Encode beta-binomial counts as a float array.

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[int])

Return type:

ndarray