mixle.stats.combinator.zero_inflated module

Zero-inflated count models: a point mass at 0 mixed with any base count distribution.

A zero-inflated distribution adds a separate source of zeros to a base count distribution: with probability pi the observation is a structural zero, and with probability 1 - pi it is drawn from base. So

P(X = 0) = pi + (1 - pi) * P_base(0), P(X = k) = (1 - pi) * P_base(k) for k > 0.

This is the standard remedy for excess zeros (ecology, insurance, defaults). Because the base can itself produce zeros, an observed 0 is ambiguous – it may be structural or a base zero – so the model is fit by EM (a two-component mixture whose inflation component is a fixed PointMass(0)). Wrapping any base gives the whole family at once: a Poisson base is the zero-inflated Poisson (ZIP), a NegativeBinomial base is ZINB, a Binomial base is zero-inflated binomial, and so on.

class ZeroInflatedDistribution(base, pi, name=None, keys=None)[source]

Bases: SequenceEncodableProbabilityDistribution

A base count distribution with an extra point mass of probability pi at zero.

Parameters:

  • base (SequenceEncodableProbabilityDistribution)

  • pi (float)

  • name (str | None)

  • keys (str | None)

density(x)[source]

Return the zero-inflated probability at x.

Parameters:

x (Any)

Return type:

float

log_density(x)[source]

Return log[(1-pi) p_base(x)] for x > 0, mixed with pi at x == 0.

Parameters:

x (Any)

Return type:

float

seq_log_density(x)[source]

Vectorized zero-inflated log-density for an encoded batch.

Parameters:

x (tuple[Any, ndarray])

Return type:

ndarray

sampler(seed=None)[source]

Return a ZeroInflatedSampler for this distribution.

Parameters:

seed (int | None)

Return type:

ZeroInflatedSampler

estimator(pseudo_count=None)[source]

Return an estimator that fits pi and the base by EM over the latent zero source.

Parameters:

pseudo_count (float | None)

Return type:

ZeroInflatedEstimator

dist_to_encoder()[source]

Return the data encoder (base encoding + a boolean is-zero mask).

Return type:

ZeroInflatedDataEncoder

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

Bases: DistributionSampler

Draw a structural zero with probability pi, otherwise draw from the base.

Parameters:

  • dist (ZeroInflatedDistribution)

  • seed (int | None)

sample(size=None)[source]

Draw one observation or a list of size observations.

Parameters:

size (int | None)

class ZeroInflatedAccumulator(base_accumulator, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate the base sufficient statistics plus the expected structural-zero count.

Parameters:

  • base_accumulator (SequenceEncodableStatisticAccumulator)

  • keys (str | None)

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

  • x (Any)

  • weight (float)

  • estimate (ZeroInflatedDistribution | None)

Return type:

None

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

None

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

None

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

None

combine(suff_stat)[source]
Parameters:

suff_stat (tuple[Any, float, float])

Return type:

ZeroInflatedAccumulator

value()[source]
Return type:

tuple[Any, float, float]

from_value(x)[source]
Parameters:

x (tuple[Any, float, float])

Return type:

ZeroInflatedAccumulator

scale(c)[source]

Scale linear sufficient statistics in-place by c.

The structural default is correct for ordinary weighted sums, nested tuples/lists/dicts, and numeric arrays. Families whose value() payload includes non-linear metadata such as support bounds must override this method and leave that metadata unscaled.

Parameters:

c (float)

Return type:

ZeroInflatedAccumulator

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:

ZeroInflatedDataEncoder

class ZeroInflatedAccumulatorFactory(base_factory, keys=None)[source]

Bases: StatisticAccumulatorFactory

Factory for ZeroInflatedAccumulator.

Parameters:

  • base_factory (StatisticAccumulatorFactory)

  • keys (str | None)

make()[source]
Return type:

ZeroInflatedAccumulator

class ZeroInflatedEstimator(base_estimator, pseudo_count=None, name=None, keys=None)[source]

Bases: ParameterEstimator

EM estimator: pi = (expected structural zeros) / N, base re-fit on the down-weighted data.

Parameters:

  • base_estimator (ParameterEstimator)

  • pseudo_count (float | None)

  • name (str | None)

  • keys (str | None)

accumulator_factory()[source]
Return type:

ZeroInflatedAccumulatorFactory

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

ZeroInflatedDistribution

class ZeroInflatedDataEncoder(base_encoder)[source]

Bases: MaskedBaseEncoder

Encode observations via the base encoder, plus a boolean x == 0 mask.

Parameters:

base_encoder (DataSequenceEncoder)