mixle.stats.univariate.discrete.negative_binomial module

Negative binomial distributions over non-negative integer counts.

The parameterization is the number of failures X before r successes, with success probability p:

P(X=x) = Gamma(x+r) / (Gamma(r) Gamma(x+1)) * p**r * (1-p)**x, x = 0, 1, 2, …

The dispersion r has no closed-form MLE; the estimator recovers it by a 1-D numerical solve of the digamma score equation (with p profiled out), then p follows in closed form. Pass estimate_r=False to hold r fixed instead.

Reference: Johnson, Kemp & Kotz, Univariate Discrete Distributions (3rd ed., Wiley, 2005).

class NegativeBinomialDistribution(r, p, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Negative binomial distribution over non-negative integer counts.

Parameters:

• r (float)

• p (float)

• name (str | None)

• keys (str | None)

classmethod compute_capabilities()

Describe backend support for generated negative-binomial kernels.

classmethod compute_declaration()

Return the structured compute declaration for negative binomial distributions.

static backend_legacy_sufficient_statistics(x, params, engine)

Return per-row negative-binomial sufficient statistics in accumulator order.

The accumulator’s NegativeBinomialAccumulator.value() returns (count, sum, histogram); the third row stat carries the per-row counts so the declaration’s kind="histogram" reducer can fold them into the weighted count histogram the dispersion (r) solve needs.

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)

Return the NegativeBinomial sufficient statistic T(x) = (x,) (r fixed).

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)

Return the NegativeBinomial natural parameter eta = log(1 - p) (r fixed).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)

Return the NegativeBinomial log partition A = -r * log(p) (r fixed).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

Any

static exp_family_base_measure_from_params(x, params, engine)

Return the NegativeBinomial base measure log h(x) = lgamma(x+r) - lgamma(r) - log(x!).

The base measure carries the binomial-coefficient term and depends on the fixed shape r; invalid (non-integer / negative) counts are mapped to -inf.

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

Any

density(x)

Return the probability density or mass at a single observation.

Parameters:

x (int)

Return type:

float

log_density(x)

Return the log-density or log-mass at a single observation.

Parameters:

x (int)

Return type:

float

seq_log_density(x)

Return vectorized log-density values for sequence-encoded observations.

Parameters:

x (tuple[ndarray, ndarray])

Return type:

ndarray

static backend_log_density_from_params(vals, log_fact, r, p, engine)

Engine-neutral negative-binomial log-density from explicit parameters.

Parameters:

• vals (Any)

• log_fact (Any)

• r (Any)

• p (Any)

• engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded data.

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked negative-binomial parameters for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[NegativeBinomialDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of negative-binomial log densities.

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

Any

to_fisher(**kwargs)

Return the NegativeBinomial’s count-family Fisher view.

mean()

Mean E[X] (failures before r successes): r(1-p)/p.

Return type:

float

variance()

Variance Var[X]: r(1-p)/p^2.

Return type:

float

cdf(x)

Cumulative distribution function P(X <= x) = I_p(r, floor(x)+1).

Parameters:

x (float)

Return type:

float

quantile(q)

Inverse CDF F^{-1}(q) (via scipy nbinom).

Parameters:

q (float)

Return type:

float

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

NegativeBinomialSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

NegativeBinomialEstimator

dist_to_encoder()

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

Return type:

NegativeBinomialDataEncoder

enumerator()

Return an enumerator over the distribution support when available.

Return type:

NegativeBinomialEnumerator

class NegativeBinomialEnumerator(dist)

Bases: DistributionEnumerator

Enumerate the infinite support in descending probability order.

Parameters:

dist (NegativeBinomialDistribution)

class NegativeBinomialSampler(dist, seed=None)

Bases: DistributionSampler

Draw iid negative binomial observations.

Parameters:

• dist (NegativeBinomialDistribution)

• seed (int | None)

sample(size=None)

Draw one sample or an array of iid samples.

Parameters:

size (int | None)

Return type:

int | ndarray

class NegativeBinomialAccumulator(name=None, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count and sum statistics plus the count histogram.

The dispersion r has no finite-dimensional sufficient statistic: its MLE needs sum_i w_i digamma(x_i + r), which cannot be reduced to count/sum. We therefore accumulate the weighted histogram {x: weight} so NegativeBinomialEstimator.estimate() can solve the score equation for r.

Parameters:

• name (str | None)

• keys (str | None)

update(x, weight, estimate)

Accumulate weighted statistics for one non-negative integer count.

Parameters:

• x (int)

• weight (float)

• estimate (NegativeBinomialDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize statistics from one observation.

Parameters:

• x (int)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Accumulate weighted statistics from encoded observations.

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• estimate (NegativeBinomialDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Initialize statistics from encoded observations.

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Merge another negative-binomial sufficient-statistic tuple.

Parameters:

suff_stat (tuple[float, float, dict[int, float]])

Return type:

NegativeBinomialAccumulator

value()

Return count, sum, and histogram statistics.

Return type:

tuple[float, float, dict[int, float]]

from_value(x)

Replace accumulator contents from a sufficient-statistic tuple.

Parameters:

x (tuple[float, float, dict[int, float]])

Return type:

NegativeBinomialAccumulator

key_merge(stats_dict)

Merge keyed statistics into stats_dict when keys are configured.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace this accumulator from keyed statistics when available.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return the encoder used by this accumulator.

Return type:

NegativeBinomialDataEncoder

class NegativeBinomialAccumulatorFactory(name=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for NegativeBinomialAccumulator.

Parameters:

• name (str | None)

• keys (str | None)

make()

Create a fresh negative-binomial accumulator.

Return type:

NegativeBinomialAccumulator

class NegativeBinomialEstimator(r=1.0, pseudo_count=None, suff_stat=None, estimate_r=True, threshold=1.0e-8, name=None, keys=None)

Bases: ParameterEstimator

Estimate r and p for a negative binomial distribution.

By default the dispersion r is recovered by a 1-D solve of the digamma score equation (p profiled out), then p follows in closed form. Pass estimate_r=False to hold r fixed at the constructor value (the historical geometric/fixed-shape M-step). The r argument is the initial value / fallback when estimate_r=True.

Parameters:

• r (float)

• pseudo_count (float | None)

• suff_stat (float | None)

• estimate_r (bool)

• threshold (float)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return an accumulator factory for negative-binomial statistics.

Return type:

NegativeBinomialAccumulatorFactory

resident_accumulation_supported()

Dispersion estimation needs the full count histogram, not fixed-width resident stats.

Return type:

bool

static estimate_dispersion(histogram, r_init, threshold)

Solve the negative-binomial dispersion MLE from a weighted count histogram.

With p profiled to its MLE p = r / (r + xbar), the score for r is

g(r) = sum_k h(k) [digamma(k + r) - digamma(r)] - N * log(1 + xbar / r),

which is strictly decreasing and crosses zero exactly when the data are over-dispersed (sample variance > mean). Under equi/under-dispersion the MLE runs off to the Poisson limit, so r is capped at _MAX_NB_SHAPE.

Parameters:

• histogram (dict[int, float])

• r_init (float)

• threshold (float)

Return type:

float

estimate(nobs, suff_stat)

Estimate r and p from weighted count statistics.

Parameters:

• nobs (float | None)

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

Return type:

NegativeBinomialDistribution

class NegativeBinomialDataEncoder

Bases: DataSequenceEncoder

Encode count observations with precomputed log-factorials.

seq_encode(x)

Encode counts with precomputed log(x!) values.

Parameters:

x (Sequence[int])

Return type:

tuple[ndarray, ndarray]