mixle.stats.univariate.discrete.geometric module¶

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

The observation type is int on support {1, 2, ...}. The log-density is (k - 1) * log(1 - p) + log(p) for k >= 1.

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

class GeometricDistribution(p, name=None, prior=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Geometric distribution on {1, 2, ...} with success probability p.

Parameters:

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

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

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

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

Return per-row Geometric sufficient statistics in accumulator order.

Parameters:

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

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)[source]

Return Geometric sufficient statistic T(x) = (x,) (support x = 1, 2, …).

Parameters:

x (Any)
engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)[source]

Return Geometric natural parameter eta = log(1 - p).

Parameters:

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

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)[source]

Return Geometric log partition A = log(1 - p) - log(p).

Parameters:

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

Return type:

Any

static exp_family_from_natural(eta)[source]

Return the Geometric with natural parameter eta = log(1 - p).

Parameters:: eta (Any)
Return type:: GeometricDistribution

set_prior(prior)[source]

Attach a Beta parameter prior and precompute conjugate-prior expectations.

With a Beta(a, b) prior on the success probability p this caches the digamma terms (digamma(a), digamma(b), digamma(a+b)) so that expected_log_density evaluates the variational Bayes expectation E_q[log p(x | p)] via E[log p] = digamma(a) - digamma(a+b) and E[log(1-p)] = digamma(b) - digamma(a+b). 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 | p)] under the Beta prior.

Uses the cached digamma expectations of log p and log(1-p); falls back to the plug-in log_density(x) when no conjugate prior is attached.

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

seq_expected_log_density(x)[source]

Vectorized expected_log_density over sequence-encoded observations.

Parameters:: x (ndarray)
Return type:: ndarray

density(x)[source]

Density of geometric distribution evaluated at x.

P(x=k) = (k-1)*log(1-p) + log(p), for x = 1,2,…, else 0.0.

Parameters:: x (int) – Observed geometric value (1,2,3,….).
Returns:: Density of geometric distribution evaluated at x.
Return type:: float

log_density(x)[source]

Log-density of geometric distribution evaluated at x.

See density() for details.

Parameters:: x (int) – Must be natural number (1,2,3,….).
Returns:: Log-density of geometric distribution evaluated at x.
Return type:: float

seq_log_density(x)[source]

Vectorized log-density evaluated on sequence encoded x.

Parameters:: x (int) – Numpy array of non-negative integers.
Returns:: Numpy array of log-density evaluated at each encoded observation value x.
Return type:: ndarray

static backend_log_density_from_params(x, p, engine)[source]

Engine-neutral geometric log-density from explicit parameters.

Parameters:

x (Any)
p (Any)
engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized log-density for encoded data.

Parameters:

x (Any)
engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)[source]

Return stacked geometric parameters for a homogeneous mixture kernel.

Parameters:

dists (Sequence[GeometricDistribution])
engine (Any)

Return type:

dict[str, Any]

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

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

Parameters:

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

Return type:

Any

to_fisher(**kwargs)[source]: Return the Geometric’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) = 1 - (1-p)^floor(x), support x >= 1.

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

quantile(q)[source]

Inverse CDF F^{-1}(q), support >= 1 (via scipy geom).

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

entropy()[source]

Shannon entropy (-(1-p) log(1-p) - p log p) / p (nats).

Return type:: float

mode()[source]

Mode (1 – the minimum of the decreasing pmf).

Return type:: float

sampler(seed=None)[source]

Create a sampler from this geometric distribution.

Parameters:: seed (Optional[int]) – Used to set seed on random number generator.
Returns:: GeometricSampler configured from this distribution.
Return type:: GeometricSampler

estimator(pseudo_count=None)[source]

Create an estimator for a geometric distribution.

Parameters:: pseudo_count (Optional[float]) – Regularize empirical summary statistics.
Returns:: GeometricEstimator configured with this distribution’s prior and name.
Return type:: GeometricEstimator

dist_to_encoder()[source]

Return the encoder for geometric observations.

Return type:: GeometricDataEncoder

enumerator()[source]

Returns GeometricEnumerator iterating the support {1, 2, …} in descending probability order.

Return type:: GeometricEnumerator

quantized_index(max_bits, bin_width_bits=1.0)[source]

Build a bounded bit-quantized index directly from the geometric tail formula.

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 exact aligned cross-bin view over bounded geometric prefixes.

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

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

Build an exact aligned cross-bin view over two bounded geometric prefixes.

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

class GeometricEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerate geometric support values in descending probability order.

Parameters:: dist (GeometricDistribution)

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

Bases: DistributionSampler

Draw independent samples from a GeometricDistribution.

Parameters:

dist (GeometricDistribution)
seed (int | None)

sample(size=None)[source]

Generate iid samples from geometric distribution.

Generates a single geometric sample (int) if size is None, else a numpy array of integers of length size, iid samples, from the geometric 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 GeometricAccumulator(name=None, keys=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count and sum statistics for Geometric estimation.

Parameters:

name (str | None)
keys (str | None)

update(x, weight, estimate)[source]

Update sufficient statistics for GeometricAccumulator with one weighted observation.

Parameters:

x (int) – Positive integer observation of geometric distribution.
weight (float) – Weight for observation.
estimate (Optional[GeometricDistribution]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None

Return type:

None

seq_update(x, weights, estimate)[source]

Vectorized update of sufficient statistics from encoded sequence x.

sum increased by sum of weighted observations. count increased by sum of weights.

Parameters:

x (ndarray) – Numpy array of positive integers.
weights (ndarray) – Numpy array of positive floats.
estimate (Optional[GeometricDistribution]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

initialize(x, weight, rng)[source]

Initialize sufficient statistics of GeometricAccumulator with weighted observation.

This delegates to update().

Parameters:

x (int) – Positive integer observation of geometric distribution.
weight (float) – Positive real-valued weight for observation x.
rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

seq_initialize(x, weights, rng)[source]

Vectorized initialization of GeometricAccumulator sufficient statistics with weighted observations.

This delegates to seq_update().

Parameters:

x (ndarray) – Numpy array of positive integers.
weights (ndarray) – Numpy array of positive floats.
rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

combine(suff_stat)[source]

Combine aggregated sufficient statistics with sufficient statistics of GeometricAccumulator 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:: GeometricAccumulator object.
Return type:: GeometricAccumulator

value()[source]

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

Return type:: tuple[float, float]

from_value(x)[source]

Sets GeometricAccumulator instance sufficient statistic member variables to x.

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

key_merge(stats_dict)[source]

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

Parameters:: stats_dict (Dict[str, Any]) – Dict mapping keys to sufficient statistics.
Returns:: None.
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]) – Dict mapping keys to sufficient statistics.
Returns:: None.
Return type:: None

acc_to_encoder()[source]

Return the encoder associated with this accumulator.

Return type:: GeometricDataEncoder

class GeometricAccumulatorFactory(name=None, keys=None)[source]

Bases: StatisticAccumulatorFactory

Create Geometric accumulators with shared name and merge-key metadata.

Parameters:

name (str | None)
keys (str | None)

make()[source]

Return GeometricAccumulator with name and keys passed.

Return type:: GeometricAccumulator

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

Bases: ParameterEstimator

Estimate Geometric success probabilities 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]

Create a geometric accumulator factory with this estimator’s name and keys.

Return type:: GeometricAccumulatorFactory

model_log_density(model)[source]

Log-density of the model’s success probability under the Beta prior (ELBO global term).

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

estimate(nobs, suff_stat)[source]

Estimate a geometric distribution from weighted count and sum statistics.

nobs is accepted for estimator API consistency but is not used. suff_stat is (count, sum). Without a pseudo-count, the estimate is p = count / sum; with a pseudo-count, the empirical statistic is shrunk toward the estimator’s prior statistic when available.

Parameters:

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

Return type:

GeometricDistribution

class GeometricDataEncoder[source]

Bases: DataSequenceEncoder

Data encoder for iid positive-integer geometric observations.

seq_encode(x)[source]

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

Note: x should be list of numpy array of positive integers.

Parameters:: x (Union[Sequence[int], np.ndarray]) – Positive integer geometric observations.
Returns:: Numpy array of positive integers.
Return type:: ndarray