mixle.stats.univariate.discrete.poisson module¶

Create, estimate, and sample from a Poisson distribution with rate lam > 0.0.

Defines the PoissonDistribution, PoissonSampler, PoissonAccumulatorFactory, PoissonAccumulator, PoissonEstimator, and the PoissonDataEncoder classes for use with mixle.

Data type (int): The Poisson distribution with rate lam, has log-density

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

for x in {0,1,2,…}, and

log(p_mat(x_mat=x)) = -np.inf,

else.

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]

classmethod compute_declaration()[source]

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]

Create PoissonSampler object with PoissonDistribution instance and seed (Optional[int]) passed.

Parameters:: seed (Optional[int]) – Optional seed for random number generator used in sampling.
Returns:: PoissonSampler object.
Return type:: PoissonSampler

estimator(pseudo_count=None)[source]

Creates PoissonEstimator object.

Parameters:: pseudo_count (Optional[float]) – If passed, used to re-weight summary statistic lam from PoissonDistribution instance.
Returns:: PoissonEstimator object.
Return type:: PoissonEstimator

dist_to_encoder()[source]

Return PoissonDataEncoder object.

Return type:: PoissonDataEncoder

enumerator()[source]

Returns PoissonEnumerator iterating the support {0, 1, …} 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

Parameters:: dist (PoissonDistribution)

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

Bases: DistributionSampler

Parameters:

dist (PoissonDistribution)
seed (int | None)

sample(size=None)[source]

Generate iid samples from Poisson distribution.

Generates a single Poisson sample (int) if size is None, else a numpy array of integers of length size containing iid samples, from the Poisson distribution.

Parameters:: size (Optional[int]) – Number of iid samples to draw. If None, assumed to be 1.
Returns:: If size is None, int, else size length numpy array of ints.
Return type:: int | ndarray

class PoissonAccumulator(keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Parameters:: keys (str | None)

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

Initialize PoissonAccumulator object with weighted observation.

Note: Just calls update().

Parameters:

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

Returns:

None.

Return type:

None

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

Vectorized initialization of PoissonAccumulator sufficient statistics with weighted observations.

Note: Just calls 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]

Combine aggregated sufficient statistics with sufficient statistics of PoissonAccumulator instance.

Input suff_stat is Tuple[float, float] with:: suff_stat[0] (float): sum of observation weights, suff_stat[1] (float): weighted sum of observations.

Parameters:: suff_stat (Tuple[float, float]) – See above for details.
Returns:: PoissonAccumulator object.
Return type:: PoissonAccumulator

value()[source]

Returns sufficient statistics Tuple[float, float] of PoissonAccumulator instance.

Return type:: tuple[float, float]

from_value(x)[source]

Sets PoissonAccumulator instance sufficient statistic member variables to x.

Parameters:: x (Tuple[float, float]) – Sum of observations weights and sum of weighted observations.
Returns:: PoissonAccumulator object.
Return type:: PoissonAccumulator

key_merge(stats_dict)[source]

Merges PoissonAccumulator sufficient statistics with sufficient statistics contained in suff_stat dict that share the same key.

Parameters:: stats_dict (Dict[str, Any]) – Dict containing ‘key’ string for PoissonAccumulator objects to combine sufficient statistics.
Returns:: None.
Return type:: None

key_replace(stats_dict)[source]

Set the sufficient statistics of PoissonAccumulator to stats_key sufficient statistics if key is in: stats_dict.

Parameters:: stats_dict (Dict[str, Any]) – Dictionary mapping keys string ids to sufficient statistics. objects.
Returns:: None.
Return type:: None

acc_to_encoder()[source]

Return PoissonDataEncoder object.

Return type:: PoissonDataEncoder

class PoissonAccumulatorFactory(keys=None)[source]

Bases: StatisticAccumulatorFactory

Parameters:: keys (str | None)

make()[source]

Returns PoissonAccumulator object with keys passed.

Return type:: PoissonAccumulator

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

Bases: ParameterEstimator

Parameters:

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

accumulator_factory()[source]

Return PoissonAccumulatorFactory object with name and keys passed.

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 lambda of PoissonDistribution from aggregated sufficient statistcs suff_stat.

Arg passed suff_stat is a Tuple of two floats containing:: suff_stat[0] (float): Aggregated sum of observation weights, suff_stat[1] (float): Aggregated sum of weighted observations.

Parameters:

nobs (Optional[float]) – Not used. Kept for consistency with ParameterEstimator.
suff_stat (tuple[float, float]) – See above for details.

Returns:

PoissonDistribution object.

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 Tuple of np.ndarray[int] of x, and np.log(Gamma(x+1.0)), where Gamma is the Gamma function.

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]