mixle.stats.univariate.discrete.poisson module¶

Poisson distributions, estimators, accumulators, samplers, and encoders.

For nonnegative integer counts, PoissonDistribution(lam) has rate lam > 0 and log-density:

log(p_mat(x_mat=x; lam)) = x*log(lam) - log(x!) - lam,

Values outside {0, 1, 2, ...} score -inf.

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

class PoissonDistribution(lam, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Poisson distribution over non-negative integer counts with rate lam.

Parameters:

lam (float)
name (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()[source]: Declare backend support for generated Poisson density kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the Poisson distribution.

static exp_family_sufficient_statistics(x, engine)[source]

Return Poisson sufficient statistics for generated scoring.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_legacy_sufficient_statistics(x, params, engine)[source]

Return per-row Poisson sufficient statistics in accumulator order.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Poisson natural parameters for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Poisson log partition for generated scoring.

Parameters:

params (dict[str, Any])
engine (Any)

Return type:

Any

static exp_family_base_measure(x, engine)[source]

Return Poisson base measure for generated scoring.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

Any

set_prior(prior)[source]

Attach a parameter prior and cache the conjugate Gamma expectations.

With a Gamma(k, theta) prior over the rate lam this caches (k, theta) so that expected_log_density(x) = (psi(k) + ln theta)*x - k*theta - gammaln(x+1) (the VB E-step term using E[ln lam] = psi(k) + ln theta and E[lam] = k*theta). Any other prior (including None) leaves the distribution a plain point model.

Parameters:: prior (SequenceEncodableProbabilityDistribution | None)
Return type:: None

expected_log_density(x)[source]

Variational expectation E_q[log p(x | lam)] under the Gamma prior.

Falls back to the plug-in log_density(x) when no conjugate prior is attached.

Parameters:: x (float)
Return type:: float

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (tuple[ndarray, ndarray])
Return type:: ndarray

density(x)[source]

Evaluate the density of Poisson distribution at observation x.

Calls np.exp(log_density(x)). See log_density() for details.

Parameters:: x (int) – Must be a non-negative integer value (0,1,2,….).
Returns:: Density of Poisson distribution evaluated at x.
Return type:: float

log_density(x)[source]

Log-density of Poisson distribution evaluated at x.

Log-density given by,: log(p_mat(x_mat=x; lam) = x*log(lam) - log(x!) - lam, for x in {0,1,2,…}

and -np.inf else.

Note: log(Gamma(x+1.0)) = log(x!), where Gamma is the gamma function.

Parameters:: x (int) – Must be a non-negative integer value (0,1,2,….).
Returns:: Log-density of Poisson distribution evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized log-density evaluated on sequence encoded x.

Arg value x (Tuple[np.ndarray[int], np.ndarray[float]]) is seq_encoded Poisson data from PoissonDataEncoder.seq_encode(), containing

x[0] (np.ndarray[int]): Non-negative integer valued Poisson iid observations, x[1] (np.ndarray[float]): np.log(Gamma(x[0]+1.0)), Gamma is the gamma function.

Parameters:: x (tuple[ndarray, ndarray]) – See above for details.
Returns:: Numpy array of log-density evaluated at each encoded observation value x.
Return type:: ndarray

static backend_log_density_from_params(vals, log_fact, lam, engine)[source]

Engine-neutral Poisson log-density from explicit parameters.

Parameters:

vals (Any)
log_fact (Any)
lam (Any)
engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (tuple[Any, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked Poisson parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[PoissonDistribution])
engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)[source]

Return an (n, k) matrix of Poisson log densities.

Parameters:

x (tuple[Any, Any])
params (dict[str, Any])
engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)[source]

Return stacked Poisson sufficient statistics using engine-resident arrays.

Parameters:

x (tuple[Any, Any])
weights (Any)
params (dict[str, Any])
engine (Any)

Return type:

tuple[Any, Any]

to_fisher(**kwargs)[source]: Return the Poisson’s count-family Fisher view.

mean()[source]

Mean E[X] of the distribution.

Return type:: float

variance()[source]

Variance Var[X] of the distribution.

Return type:: float

cdf(x)[source]

Cumulative distribution function P(X <= x) = Q(floor(x)+1, lam).

Parameters:: x (float)
Return type:: float

skewness()[source]

Skewness 1/sqrt(lambda).

Return type:: float

kurtosis()[source]

Excess kurtosis 1/lambda.

Return type:: float

quantile(q)[source]

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

Parameters:: q (float)
Return type:: float

mode()[source]

Mode floor(lambda).

Return type:: float

sampler(seed=None)[source]

Return a sampler for iid draws from this distribution.

Parameters:: seed (int | None) – Optional seed for the sampler’s random state.
Returns:: A configured PoissonSampler.
Return type:: PoissonSampler

estimator(pseudo_count=None)[source]

Return an estimator initialized from this distribution’s shape.

Parameters:: pseudo_count (float | None) – Optional smoothing count applied to the current rate.
Returns:: A PoissonEstimator.
Return type:: PoissonEstimator

dist_to_encoder()[source]

Return an encoder for iid Poisson observations.

Return type:: PoissonDataEncoder

enumerator()[source]

Return an enumerator over nonnegative counts in descending probability order.

Return type:: PoissonEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index by walking the Poisson mode outward.

Parameters:

max_bits (float)
bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)[source]

Build an aligned cross-bin view over bounded Poisson high-mass regions.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)[source]

Build an aligned cross-bin view over two bounded Poisson high-mass regions.

Parameters:: bin_width_bits (float)
Return type:: QuantizedCrossIndex

class PoissonEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate Poisson support values in descending probability order.

Parameters:: dist (PoissonDistribution)

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

Bases: DistributionSampler

Draw independent samples from a PoissonDistribution.

Parameters:

dist (PoissonDistribution)
seed (int | None)

sample(size=None)[source]

Draw iid samples from the Poisson distribution.

Parameters:: size (int | None) – Number of iid samples to draw. None returns a scalar sample.
Returns:: A scalar draw when size is None; otherwise an array of draws.
Return type:: int | ndarray

class PoissonAccumulator(keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count and sum statistics for Poisson estimation.

Parameters:: keys (str | None)

initialize(x, weight, rng=None)[source]

Initialize sufficient statistics with one weighted observation.

This method delegates to update.

Parameters:

x (int) – Observation from a Poisson distribution.
weight (float) – Observation weight.
rng (RandomState | None) – Unused; accepted for the accumulator interface.

Return type:

None

seq_initialize(x, weights, rng=None)[source]

Vectorized initialization of PoissonAccumulator sufficient statistics with weighted observations.

This delegates to seq_update().

Arg value x (Tuple[np.ndarray[int], np.ndarray[float]]) is seq_encoded Poisson data from PoissonDataEncoder.seq_encode(), containing

x[0] (np.ndarray[int]): Non-negative integer valued Poisson iid observations, x[1] (np.ndarray[float]): np.log(Gamma(x[0]+1.0)), Gamma is the gamma function.

Parameters:

x (tuple[ndarray, ndarray]) – See above for details.
weights (ndarray) – Numpy array of positive floats.
rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

update(x, weight, estimate=None)[source]

Update sufficient statistics for PoissonAccumulator with one weighted observation.

Parameters:

x (int) – Observation from Poisson distribution.
weight (float) – Weight for observation.
estimate (Optional[PoissonDistribution]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

seq_update(x, weights, estimate=None)[source]

Vectorized update of PoissonAccumulator sufficient statistics with weighted observations.

Arg value x (Tuple[np.ndarray[int], np.ndarray[float]]) is seq_encoded Poisson data from PoissonDataEncoder.seq_encode(), containing

x[0] (np.ndarray[int]): Non-negative integer valued Poisson iid observations, x[1] (np.ndarray[float]): np.log(Gamma(x[0]+1.0)), Gamma is the gamma function.

Parameters:

x (tuple[ndarray, ndarray]) – See above for details.
weights (ndarray) – Numpy array of positive floats.
estimate (Optional[PoissonDistribution]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

combine(suff_stat)[source]

Merge aggregated Poisson sufficient statistics into this accumulator.

The tuple is interpreted as (count, sum).

Parameters:: suff_stat (tuple[float, float]) – Aggregated Poisson sufficient statistics.
Returns:: This accumulator.
Return type:: PoissonAccumulator

value()[source]

Return sufficient statistics as (count, sum).

Return type:: tuple[float, float]

from_value(x)[source]

Replace this accumulator’s sufficient statistics.

Parameters:: x (tuple[float, float]) – Aggregated Poisson sufficient statistics as (count, sum).
Returns:: This accumulator.
Return type:: PoissonAccumulator

key_merge(stats_dict)[source]

Merge this accumulator into stats_dict under its configured key.

Parameters:: stats_dict (dict[str, Any]) – Mapping from merge keys to Poisson accumulators.
Return type:: None

key_replace(stats_dict)[source]

Replace sufficient statistics from stats_dict when this accumulator’s key is present.

Parameters:: stats_dict (dict[str, Any]) – Mapping from keys to compatible sufficient statistics.
Return type:: None

acc_to_encoder()[source]

Return an encoder compatible with Poisson observations.

Return type:: PoissonDataEncoder

class PoissonAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Create Poisson accumulators with a shared optional merge key.

Parameters:: keys (str | None)

make()[source]

Return a fresh Poisson accumulator.

Return type:: PoissonAccumulator

class PoissonEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)[source]

Bases: ParameterEstimator

Estimate Poisson rate parameters from accumulated sufficient statistics.

Parameters:

pseudo_count (float | None)
suff_stat (float | None)
name (str | None)
keys (str | None)
prior (SequenceEncodableProbabilityDistribution | None)

accumulator_factory()[source]

Return an accumulator factory matching this estimator.

Return type:: PoissonAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s rate under the Gamma prior (ELBO global term).

Parameters:: model (PoissonDistribution)
Return type:: float

estimate(nobs, suff_stat)[source]

Estimate a Poisson distribution from aggregated sufficient statistics.

The tuple is interpreted as (count, sum).

Parameters:

nobs (float | None) – Unused; accepted for the ParameterEstimator interface.
suff_stat (tuple[float, float]) – Aggregated Poisson sufficient statistics.

Returns:

A fitted Poisson distribution.

Return type:

PoissonDistribution

class PoissonDataEncoder[source]

Bases: DataSequenceEncoder

Encode iid non-negative integer Poisson observations with log-factorials.

seq_encode(x)[source]

Encode iid sequence of Poisson observations for vectorized “seq_” function calls.

Data type must be int. Values must be non-negative integers. Returns the integer observations and log(Gamma(x + 1)) values used by the vectorized scorer.

Parameters:: x (Union[np.ndarray, Sequence[int]]) – Sequence of iid non-negative integers valued Poisson observations.
Returns:: Tuple[ndarray[int], ndarray[float]].
Return type:: tuple[ndarray, ndarray]