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]

Accumulate one observation with EM responsibility for structural zeros.

Parameters:

x (Any)
weight (float)
estimate (ZeroInflatedDistribution | None)

Return type:

None

seq_update(x, weights, estimate)[source]

Accumulate encoded observations with zero-source responsibilities.

Parameters:

x (tuple[Any, ndarray])
weights (ndarray)
estimate (ZeroInflatedDistribution)

Return type:

None

initialize(x, weight, rng)[source]

Initialize the accumulator using a half-structural responsibility for zeros.

Parameters:

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

Return type:

None

seq_initialize(x, weights, rng)[source]

Initialize encoded observations using half-structural zero responsibilities.

Parameters:

x (tuple[Any, ndarray])
weights (ndarray)
rng (RandomState | None)

Return type:

None

combine(suff_stat)[source]

Merge serialized base statistics and inflation counts into this accumulator.

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

value()[source]

Return base statistics, expected structural-zero weight, and total weight.

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

from_value(x)[source]

Restore the accumulator from serialized zero-inflated statistics.

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

scale(c)[source]

Scale base statistics and inflation counts by a constant.

Parameters:: c (float)
Return type:: ZeroInflatedAccumulator

key_merge(stats_dict)[source]

Merge base and inflation statistics into a keyed statistics dictionary.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

key_replace(stats_dict)[source]

Replace base and inflation statistics from a keyed statistics dictionary.

Parameters:: stats_dict (dict[str, Any])
Return type:: None

acc_to_encoder()[source]

Return an encoder that augments the base encoding with a zero mask.

Return type:: ZeroInflatedDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for ZeroInflatedAccumulator.

Parameters:

base_factory (StatisticAccumulatorFactory)
keys (str | None)

make()[source]

Create an empty zero-inflated accumulator.

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 a factory for zero-inflated sufficient-statistic accumulators.

Return type:: ZeroInflatedAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate the base distribution and structural-zero probability.

Parameters:

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

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)