mixle.stats.multivariate.dirichlet_multinomial module

Dirichlet-multinomial (Polya) distribution – an overdispersed multinomial.

The multivariate analogue of the beta-binomial: a multinomial whose category probabilities are Dirichlet(alpha) distributed and integrated out. For a count vector x over K categories summing to n,

P(x; alpha) = n!/prod_k x_k! * B(alpha + x) / B(alpha), B(a) = prod_k Gamma(a_k) / Gamma(sum a),

which adds overdispersion (and category correlation) over a plain multinomial. The number of trials n is a fixed, known parameter; alpha is fit by Minka’s maximum-likelihood fixed point, run from a cumulative-count sufficient statistic so it converges inside a single estimate call.

exception DirichletMultinomialResourceError

Bases: RuntimeError

Raised before a configured enumeration or fitting resource budget is exceeded.

class DirichletMultinomialFitReceipt(algorithm, converged, identifiable, iterations, objective_history, max_delta, regularized_categories, concentration_floor)

Bases: object

Machine-readable evidence about a concentration fixed-point fit.

Parameters:

• algorithm (str)

• converged (bool)

• identifiable (bool)

• iterations (int)

• objective_history (tuple[float, ...])

• max_delta (float)

• regularized_categories (tuple[int, ...])

• concentration_floor (float)

class DirichletMultinomialDistribution(alpha, n, name=None, keys=None, *, max_recurrence_cells=_DEFAULT_MAX_RECURRENCE_CELLS, max_frontier_entries=_DEFAULT_MAX_FRONTIER_ENTRIES)

Bases: SequenceEncodableProbabilityDistribution

Dirichlet-multinomial over K-category count vectors summing to n (concentration alpha).

Parameters:

• alpha (ndarray)

• n (int)

• name (str | None)

• keys (str | None)

• max_recurrence_cells (int)

• max_frontier_entries (int)

density(x)

Return the probability mass at a single count vector x.

Parameters:

x (ndarray)

Return type:

float

log_density(x)

Return the log-mass at x (-inf if any count is negative, non-integer, or the total is not n – a fractional category count is not a valid Dirichlet-multinomial outcome even when the (real-valued) total happens to sum to n).

Parameters:

x (ndarray)

Return type:

float

seq_log_density(x)

Vectorized log-mass for a stack of count vectors, shape (N, K) (-inf rows where any count is negative, non-integer, or the row total is not n).

Parameters:

x (ndarray)

Return type:

ndarray

sampler(seed=None)

Return a sampler for drawing count vectors from this distribution.

Parameters:

seed (int | None)

Return type:

DirichletMultinomialSampler

estimator(pseudo_count=None)

Return a Minka fixed-point MLE estimator for alpha at the fixed number of trials n.

Parameters:

pseudo_count (float | None)

Return type:

DirichletMultinomialEstimator

dist_to_encoder()

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

Return type:

DirichletMultinomialDataEncoder

enumerator(*, max_recurrence_cells=None, max_frontier_entries=None)

Return an enumerator over count vectors summing to n in descending probability order.

Parameters:

• max_recurrence_cells (int | None)

• max_frontier_entries (int | None)

Return type:

DirichletMultinomialEnumerator

class DirichletMultinomialEnumerator(dist, *, max_recurrence_cells=_DEFAULT_MAX_RECURRENCE_CELLS, max_frontier_entries=_DEFAULT_MAX_FRONTIER_ENTRIES)

Bases: DistributionEnumerator

Enumerate Dirichlet-multinomial count vectors in descending probability order, lazily (A* best-first).

The log-mass separates per category: log P(x) = log_const + sum_k f_k(x_k) with f_k(c) = gammaln(c + alpha_k) - gammaln(alpha_k) - gammaln(c + 1), and each f_k is monotone in c (increasing for alpha_k > 1, decreasing for alpha_k < 1), so a prefix assignment (x_1..x_j) with m trials left admits the admissible completion bound sum_{k>j} max(f_k(0), f_k(m)). A* on the exact prefix score plus that bound streams count vectors in exact descending order without materializing the C(n+K-1, K-1) support.

Parameters:

• dist (DirichletMultinomialDistribution)

• max_recurrence_cells (int)

• max_frontier_entries (int)

class DirichletMultinomialSampler(dist, seed=None)

Bases: DistributionSampler

Draw counts as p ~ Dirichlet(alpha) then x ~ Multinomial(n, p).

Parameters:

• dist (DirichletMultinomialDistribution)

• seed (int | None)

sample(size=None, *, batched=True)

Draw one count vector or a stack of iid count vectors.

Parameters:

• size (int | None)

• batched (bool)

Return type:

ndarray

class DirichletMultinomialAccumulator(dim, n, name=None, keys=None, *, max_recurrence_cells=_DEFAULT_MAX_RECURRENCE_CELLS)

Bases: SequenceEncodableStatisticAccumulator

Accumulate cumulative counts c[k, j] = sum_i w_i 1{x_ik > j} (the Minka digamma-recurrence stat).

Parameters:

• dim (int)

• n (int)

• name (str | None)

• keys (str | None)

• max_recurrence_cells (int)

update(x, weight, estimate)

Accumulate Minka recurrence statistics for one count vector.

Parameters:

• x (ndarray)

• weight (float)

• estimate (DirichletMultinomialDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize statistics from one count vector.

Parameters:

• x (ndarray)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Accumulate Minka recurrence statistics from encoded count vectors.

Parameters:

• x (ndarray)

• weights (ndarray)

• estimate (Any)

Return type:

None

seq_initialize(x, weights, rng)

Initialize statistics from encoded count vectors.

Parameters:

• x (ndarray)

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge another Dirichlet-multinomial sufficient-statistic tuple.

Parameters:

suff_stat (tuple[ndarray, float, int])

Return type:

DirichletMultinomialAccumulator

value()

Return cumulative recurrence counts, total weight, and logical trial count.

Return type:

tuple[ndarray, float, int]

from_value(x)

Replace accumulator contents from recurrence statistics.

Parameters:

x (tuple[ndarray, float, int])

Return type:

DirichletMultinomialAccumulator

acc_to_encoder()

Return the encoder used by this accumulator.

Return type:

DirichletMultinomialDataEncoder

class DirichletMultinomialAccumulatorFactory(dim, n, name=None, keys=None, *, max_recurrence_cells=_DEFAULT_MAX_RECURRENCE_CELLS)

Bases: StatisticAccumulatorFactory

Factory for DirichletMultinomialAccumulator.

Parameters:

• dim (int)

• n (int)

• name (str | None)

• keys (str | None)

• max_recurrence_cells (int)

make()

Create a fresh Dirichlet-multinomial accumulator.

Return type:

DirichletMultinomialAccumulator

class DirichletMultinomialEstimator(dim, n, max_iter=500, tol=1.0e-9, pseudo_count=None, name=None, keys=None, min_alpha=_DEFAULT_MIN_ALPHA, max_recurrence_cells=_DEFAULT_MAX_RECURRENCE_CELLS, max_frontier_entries=_DEFAULT_MAX_FRONTIER_ENTRIES)

Bases: ParameterEstimator

Minka fixed-point maximum-likelihood estimator for the Dirichlet-multinomial concentration.

Parameters:

• dim (int)

• n (int)

• max_iter (int)

• tol (float)

• pseudo_count (float | None)

• name (str | None)

• keys (str | None)

• min_alpha (float)

• max_recurrence_cells (int)

• max_frontier_entries (int)

accumulator_factory()

Return an accumulator factory for Dirichlet-multinomial statistics.

Return type:

DirichletMultinomialAccumulatorFactory

estimate(nobs, suff_stat)

Estimate concentration parameters by Minka’s fixed-point update.

Parameters:

• nobs (float | None)

• suff_stat (tuple[ndarray, float, int])

Return type:

DirichletMultinomialDistribution

class DirichletMultinomialDataEncoder(dim, n)

Bases: DataSequenceEncoder

Encode a sequence of K-category count vectors as an (N, K) array.

Parameters:

• dim (int)

• n (int)

seq_encode(x)

Validate and encode count vectors as an integral matrix.

Parameters:

x (Sequence[ndarray])

Return type:

ndarray