mixle.stats.univariate.discrete.logseries module

Create, estimate, and sample from a logarithmic (log-series) distribution on positive integers.

Defines the LogSeriesDistribution, LogSeriesSampler, LogSeriesAccumulatorFactory, LogSeriesAccumulator, LogSeriesEstimator, and the LogSeriesDataEncoder classes for use with mixle.

Data type: (int): a positive integer k >= 1. The LogSeriesDistribution with shape p in (0, 1) has log-mass

log(P(k; p)) = k*log(p) - log(k) - log(-log(1 - p)), k = 1, 2, …,

a one-parameter exponential family used for over-dispersed positive counts (species abundance, word-frequency / type-token models). The mean is -p / ((1 - p) * log(1 - p)) (a value in (1, inf) that increases with p), which the estimator inverts.

The per-row score is linear in the encoded k and log(k) fields once the scalar normalizer log(-log(1 - p)) is precomputed, so the family gets generated NumPy, Torch, and Numba kernels.

Reference: Fisher, Corbet & Williams, ‘The relation between the number of species and the number of individuals…’, J. Animal Ecology (1943).

class LogSeriesDistribution(p, name=None, keys=None)

Bases: SequenceEncodableProbabilityDistribution

Logarithmic (log-series) distribution on k = 1, 2, … with shape parameter p in (0, 1).

Parameters:

• p (float)

• name (str | None)

• keys (str | None)

classmethod compute_capabilities()

classmethod compute_declaration()

static backend_legacy_sufficient_statistics(x, params, engine)

Return per-row (count, k) sufficient statistics in accumulator order.

Parameters:

• x (tuple[Any, Any])

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics(x, engine)

Return the log-series sufficient statistic T(k) = (k,).

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)

Return the log-series natural parameter eta = log(p).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)

Return the log-series log partition A = log(-log(1 - p)).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

Any

static exp_family_base_measure(x, engine)

Return the log-series base measure log h(k) = -log(k) (independent of p, fixed base).

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

Any

static exp_family_from_natural(eta)

Return the log-series with natural parameter eta = log(p) (so p = exp(eta)).

Parameters:

eta (Any)

Return type:

LogSeriesDistribution

static backend_log_density_from_params(k, log_k, log_p, log_norm, engine)

Engine-neutral log-series log-mass from explicit parameters (linear in k and log k).

Parameters:

• k (Any)

• log_k (Any)

• log_p (Any)

• log_norm (Any)

• engine (Any)

Return type:

Any

density(x)

Return the probability mass at a single observation.

Parameters:

x (int)

Return type:

float

log_density(x)

Return the log-mass at a single positive integer (or -inf off support).

Parameters:

x (int)

Return type:

float

seq_log_density(x)

Return vectorized log-mass values for sequence-encoded (k, log k) observations.

Parameters:

x (tuple[ndarray, ndarray])

Return type:

ndarray

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-mass for encoded data.

Parameters:

• x (tuple[Any, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked parameters for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[LogSeriesDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of log-series 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)

Return stacked sufficient statistics using engine-resident arrays.

Parameters:

• x (tuple[Any, Any])

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any]

mean()

Mean E[X] = -p / ((1-p) log(1-p)).

Return type:

float

variance()

Variance Var[X] = -p (p + log(1-p)) / ((1-p)^2 log(1-p)^2).

Return type:

float

cdf(x)

Cumulative distribution function P(X <= x), support x >= 1 (via scipy logser).

Parameters:

x (float)

Return type:

float

quantile(q)

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

Parameters:

q (float)

Return type:

float

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

LogSeriesSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

LogSeriesEstimator

dist_to_encoder()

Return the data encoder used by this distribution for vectorized methods.

Return type:

LogSeriesDataEncoder

class LogSeriesSampler(dist, seed=None)

Bases: DistributionSampler

Draw iid log-series observations.

Parameters:

• dist (LogSeriesDistribution)

• seed (int | None)

sample(size=None)

Draw size iid positive integers (an int when size is None).

Parameters:

size (int | None)

Return type:

int | ndarray

class LogSeriesAccumulator(keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulate weighted count and sum for log-series estimation.

Parameters:

keys (str | None)

update(x, weight, estimate)

Parameters:

• x (int)

• weight (float)

• estimate (LogSeriesDistribution | None)

Return type:

None

initialize(x, weight, rng)

Parameters:

• x (int)

• weight (float)

• rng (RandomState | None)

Return type:

None

seq_update(x, weights, estimate)

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• estimate (LogSeriesDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Parameters:

• x (tuple[ndarray, ndarray])

• weights (ndarray)

• rng (RandomState | None)

Return type:

None

combine(suff_stat)

Parameters:

suff_stat (tuple[float, float])

Return type:

LogSeriesAccumulator

value()

Return type:

tuple[float, float]

from_value(x)

Parameters:

x (tuple[float, float])

Return type:

LogSeriesAccumulator

key_merge(stats_dict)

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)

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()

Return type:

LogSeriesDataEncoder

class LogSeriesAccumulatorFactory(keys=None)

Bases: StatisticAccumulatorFactory

Factory for LogSeriesAccumulator.

Parameters:

keys (str | None)

make()

Return type:

LogSeriesAccumulator

class LogSeriesEstimator(pseudo_count=None, suff_stat=None, name=None, keys=None)

Bases: ParameterEstimator

Maximum-likelihood estimator for the log-series shape p (inverts the mean -> p relation).

Parameters:

• pseudo_count (float | None)

• suff_stat (float | None)

• name (str | None)

• keys (str | None)

accumulator_factory()

Return type:

LogSeriesAccumulatorFactory

estimate(nobs, suff_stat)

Parameters:

• nobs (float | None)

• suff_stat (tuple[float, float])

Return type:

LogSeriesDistribution

class LogSeriesDataEncoder

Bases: DataSequenceEncoder

Encode log-series observations as (k, log k) pairs.

seq_encode(x)

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[int])

Return type:

tuple[ndarray, ndarray]