mixle.stats.multivariate.integer_multinomial module

Integer-keyed multinomial distributions over a bounded support.

Each observation is a sequence of (integer_category, count) pairs over [min_val, max_val]. Given category probabilities p = (p_0, ..., p_K) and a trial-count distribution P_len(N), the model scores the unnormalized log-density

log(P(x,N|p)) = sum_{k=0}^{K} x_k * log(p_k) + log(P_len(N))

where P_len(N) is a distribution for the number of trials in the multinomial. The multinomial coefficient (log(N!) - sum_k log(x_k!)) is intentionally omitted, so this is a per-category scoring form rather than a normalized probability mass over count vectors.

class IntegerMultinomialDistribution(min_val=0, p_vec=None, len_dist=NullDistribution(), name=None, keys=None, prob_vec=None)

Bases: SequenceEncodableProbabilityDistribution

Multinomial distribution over integer-keyed count maps.

Parameters:

• min_val (int)

• p_vec (list[float])

• len_dist (SequenceEncodableProbabilityDistribution | None)

• name (str | None)

• keys (str | None)

• prob_vec (list[float])

compute_capabilities()

Declare generated-compute support inherited from the trial-count distribution.

compute_declaration()

Return the generated-compute declaration for the integer multinomial.

static exp_family_sufficient_statistics(x, engine)

Return a shape-only fallback; category-aware count vectors come from ..._from_params.

Parameters:

• x (Any)

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_sufficient_statistics_from_params(x, params, engine)

Return the per-category count vector T(x) of shape (sz, K) (counts of in-support values).

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_natural_parameters(params, engine)

Return the natural parameter eta = log(p_vec) (one entry per category).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, …]

static exp_family_log_partition(params, engine)

Return the log partition A = 0 (normalization is carried by eta = log p).

Parameters:

• params (dict[str, Any])

• engine (Any)

Return type:

Any

static exp_family_base_measure_from_params(x, params, engine)

Return log h = 0 for observations whose values are all in support, -inf otherwise.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

density(x)

Evaluate the density of IntegerMultinomialDistribution at observed value x.

Parameters:

x (Sequence[Tuple[int, float]]) – Sequence of Tuple(s) containing the integer category value and number of successes.

Returns:

Density at x.

Return type:

float

log_density(x)

Evaluate the log-density of IntegerMultinomialDistribution at observed value x.

Un-normalized log-density given by

log(p_mat(x)) = sum_k x_k*log(p_k), for x having k integer categories.

Note: x has k integer values and p_k denotes the probability of success for integer-category x_k. The multinomial coefficient is intentionally omitted (see the module docstring), so this is a per-category scoring form, not a normalized mass over count vectors.

Parameters:

x (Sequence[Tuple[int, float]]) – Sequence of Tuple(s) containing the integer category value and number of successes.

Returns:

Log-density at x.

Return type:

float

seq_log_density(x)

Vectorized evaluation of log-density for an encoded sequence of iid observations from integer multinomial

distribution.

Arg ‘x’ is a Tuple of length 5 containing:

sz (int): Total number of observed integermultinomial samples. idx (ndarray): Numpy index array for each Tuple[value, count] in flattened x. cnt (ndarray): Number of successes for each value in flattened x. val (ndarray): Integer-category value array in flattened x. tcnt (Optional[T1]): Sequence encoded number of trials for each sequence (length sz), with type T if

length DataSequenceEncoder is not NullDataEncoder and returns type T. Else None.

Parameters:

x (See above for details) – Sequence encoding of iid integer multinomial observation.

Returns:

Numpy array of log-density evaluated at each observation in encoding.

Return type:

ndarray

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded integer count vectors.

Parameters:

• x (tuple[int, ndarray, ndarray, ndarray, E0 | None])

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked integer-count-vector parameters for homogeneous mixture kernels.

Parameters:

• dists (Sequence[IntegerMultinomialDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

Return an (n, k) matrix of integer-multinomial log densities.

Parameters:

• x (tuple[int, ndarray, ndarray, ndarray, E0 | None])

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics_with_estimator(x, weights, params, engine, estimator)

Return per-component legacy (min_val, count_vec, length_stat) statistics.

Parameters:

• x (tuple[int, ndarray, ndarray, ndarray, E0 | None])

• weights (Any)

• params (dict[str, Any])

• engine (Any)

• estimator (Any)

Return type:

tuple[Any, …]

sampler(seed=None)

Create a sampler for this integer multinomial distribution.

Parameters:

seed (Optional[int]) – Set seed on random number generator used in sampling.

Returns:

Sampler bound to this distribution.

Return type:

IntegerMultinomialSampler

estimator(pseudo_count=None)

Create an estimator initialized from this distribution.

Parameters:

pseudo_count (Optional[float]) – Optional prior mass assigned to this distribution’s current category probabilities during estimation.

Returns:

Estimator configured with the same support, name, and length estimator.

Return type:

IntegerMultinomialEstimator

dist_to_encoder()

Return a data encoder using the encoder supplied by len_dist.

Return type:

IntegerMultinomialDataEncoder

enumerator()

Returns IntegerMultinomialEnumerator iterating count vectors in descending log-density order.

Return type:

IntegerMultinomialEnumerator

class IntegerMultinomialEnumerator(dist)

Bases: DistributionEnumerator

Enumerates integer count vectors (lists of (category, count) pairs) in descending log-density order.

Parameters:

dist (IntegerMultinomialDistribution)

class IntegerMultinomialSampler(dist, seed=None)

Bases: DistributionSampler

Draw sparse integer-category count vectors from an integer multinomial.

Parameters:

• dist (IntegerMultinomialDistribution)

• seed (int | None)

sample(size=None)

Draw independent samples from an integer multinomial distribution.

Parameters:

size (Optional[int]) – Number of samples to draw.

Returns:

List length size containing List[Tuple[int, float]]. If size is None, returns one sample

List[Tuple[int, float]].

Return type:

list[tuple[int, float]] | list[list[tuple[int, float]]]

class IntegerMultinomialAccumulator(min_val=None, max_val=None, name=None, keys=None, len_accumulator=NullAccumulator())

Bases: SequenceEncodableStatisticAccumulator

Accumulate sparse integer-category counts and trial-count child statistics.

Parameters:

• min_val (int | None)

• max_val (int | None)

• name (str | None)

• keys (str | None)

• len_accumulator (SequenceEncodableStatisticAccumulator | None)

update(x, weight, estimate)

Update sufficient statistics from single data observation.

Parameters:

• x (Sequence[Tuple[int, float]]) – Single observation of integer multinomial distribution.

• weight (float) – Weight for observation.

• estimate (Optional[IntegerMultinomialDistribution]) – Optional previous estimate of integer multinomial distribution.

Returns:

None.

Return type:

None

initialize(x, weight, rng)

Initialize IntegerMultinomialAccumulator with single observation x.

Just calls update() method.

Parameters:

• x (Sequence[Tuple[int, float]]) – Single observation of integer multinomial distribution.

• weight (float) – Weight for observation.

• rng (Optional[RandomState]) – Optional random state for consistency with SequenceEncodableStatisticAccumulator class.

Returns:

None.

Return type:

None

seq_update(x, weights, estimate)

Vectorized update of IntegerMultinomialAccumulator sufficient statistics for encoded sequence of

independent observations x.

Encoded sequence ‘x’ is a Tuple of length 5 containing:

sz (int): Total number of observed integermultinomial samples. idx (ndarray): Numpy index array for each Tuple[value, count] in flattened x. cnt (ndarray): Number of successes for each value in flattened x. val (ndarray): Integer-category value array in flattened x. tcnt (Optional[E0]): Sequence encoded number of trials for each sequence (length sz), with type E0 if

length DataSequenceEncoder is not NullDataEncoder and returns type E0.

Parameters:

• x (See above) – Encoded sequence of iid observations of integer multinomial distribution.

• weights (ndarray) – Weights for observations in encoded sequence.

• estimate (Optional[IntegerMultinomialDistribution]) – Optional previous estimate of integer multinomial distribution.

Returns:

None.

Return type:

None

seq_update_engine(x, weights, estimate, engine)

Engine-resident accumulation of integer-multinomial count statistics (numpy or torch).

The weighted category histogram is reduced on the active engine; the dynamic support range is host bookkeeping. The length child is routed through the engine via child_seq_update. Matches seq_update.

Parameters:

• x (tuple[int, ndarray, ndarray, ndarray, E0 | None])

• weights (Any)

• estimate (IntegerMultinomialDistribution | None)

• engine (Any)

Return type:

None

seq_initialize(x, weights, rng)

Vectorized initialization of sufficient statistics from encoded sequence of iid observations ‘x’.

This delegates to seq_update().

Encoded sequence ‘x’ is a Tuple of length 5 containing:

sz (int): Total number of observed integermultinomial samples. idx (ndarray): Numpy index array for each Tuple[value, count] in flattened x. cnt (ndarray): Number of successes for each value in flattened x. val (ndarray): Integer-category value array in flattened x. tcnt (Optional[T1]): Sequence encoded number of trials for each sequence (length sz), with type E0 if

length DataSequenceEncoder is not NullDataEncoder and returns type E0. Else None.

Parameters:

• x (See above) – Encoded sequence of iid observations of integer multinomial distribution.

• weights (ndarray) – Weights for observations in encoded sequence.

• rng (Optional[RandomState]) – Optional random state for consistency with SequenceEncodableStatisticAccumulator class.

Returns:

None.

Return type:

None

combine(suff_stat)

Combine another integer multinomial sufficient-statistics tuple into this accumulator.

Arg ‘suff_stat’ contains:

suff_stat[0] (int): A minimum value for aggregated counts. suff_stat[1] (np.ndarray): Numpy array of aggregated counts. suff_stat[2] (Optional[SS0]): Optional sufficient statistics for the length accumulator with type SS0.

Parameters:

suff_stat (tuple[int, ndarray, SS0 | None]) – See above for details.

Returns:

IntegerMultinomialAccumulator object.

Return type:

IntegerMultinomialAccumulator

value()

Return accumulated sufficient statistics.

The returned tuple contains:

suff_stat[0] (int): Minimum integer category represented by the count vector. suff_stat[1] (np.ndarray): Weighted counts for consecutive integer categories. suff_stat[2] (Optional[SS0]): Sufficient statistics from the length accumulator.

Returns:

Tuple[int, ndarray, Optional[SS0]].

Return type:

tuple[int, ndarray, Any | None]

from_value(x)

Restore accumulator state from sufficient statistics.

The input tuple contains:

x[0] (int): Minimum integer category represented by the count vector. x[1] (np.ndarray): Weighted counts for consecutive integer categories. x[2] (Optional[SS0]): Sufficient statistics for the length accumulator.

Parameters:

x (See above for details)

Returns:

This accumulator after restoration.

Return type:

IntegerMultinomialAccumulator

key_merge(stats_dict)

Merge this accumulator into stats_dict when it has a matching key.

Parameters:

stats_dict (Dict[str, Any]) – Mapping from statistic keys to accumulators.

Returns:

None.

Return type:

None

key_replace(stats_dict)

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

Parameters:

stats_dict (Dict[str, Any]) – Mapping from statistic keys to accumulators.

Returns:

None.

Return type:

None

acc_to_encoder()

Return a data encoder using the encoder supplied by the length accumulator.

Return type:

IntegerMultinomialDataEncoder

class IntegerMultinomialAccumulatorFactory(min_val=None, max_val=None, name=None, keys=None, len_factory=NullAccumulatorFactory())

Bases: StatisticAccumulatorFactory

Create integer multinomial accumulators with optional length accumulators.

Parameters:

• min_val (int | None)

• max_val (int | None)

• name (str | None)

• keys (str | None)

• len_factory (StatisticAccumulatorFactory | None)

make()

Return a new integer multinomial accumulator.

Return type:

IntegerMultinomialAccumulator

class IntegerMultinomialEstimator(min_val=None, max_val=None, len_estimator=NullEstimator(), len_dist=None, name=None, pseudo_count=None, suff_stat=None, keys=None)

Bases: ParameterEstimator

Estimate integer-category multinomial probabilities from count statistics.

Parameters:

• min_val (int | None)

• max_val (int | None)

• len_estimator (ParameterEstimator | None)

• len_dist (SequenceEncodableProbabilityDistribution | None)

• name (str | None)

• pseudo_count (float | None)

• suff_stat (tuple[int, ndarray] | None)

• keys (str | None)

accumulator_factory()

Return an accumulator factory configured from this estimator.

Return type:

IntegerMultinomialAccumulatorFactory

estimate(nobs, suff_stat)

Estimate a distribution from aggregated sufficient statistics.

If pseudo_count is not set, prior sufficient statistics are ignored during estimation.

suff_stat contains:

suff_stat[0] (int): Minimum integer category represented by the count vector. suff_stat[1] (np.ndarray): Weighted counts for consecutive integer categories. suff_stat[2] (Optional[SS0]): Sufficient statistics for the length estimator.

Parameters:

• nobs (Optional[float]) – Number of observations in accumulated data.

• suff_stat (tuple[int, ndarray, SS0 | None]) – See above for details.

Returns:

Estimated distribution.

Return type:

IntegerMultinomialDistribution

class IntegerMultinomialDataEncoder(len_encoder=NullDataEncoder())

Bases: DataSequenceEncoder

Encode sparse integer multinomial observations for vectorized scoring.

Parameters:

len_encoder (DataSequenceEncoder | None)

seq_encode(x)

Encode a sequence of iid integer multinomial observations.

The returned tuple contains:

sz (int): Total number of observed integermultinomial samples. idx (ndarray): Numpy index array for each Tuple[value, count] in flattened x. cnt (ndarray): Number of successes for each value in flattened x. val (ndarray): Integer-category value array in flattened x. tcnt (Optional[E0]): Sequence encoded number of trials for each sequence (length sz), with type E0 if

length DataSequenceEncoder is not NullDataEncoder and returns type E0. Else None.

Parameters:

x (Sequence[Sequence[Tuple[int, float]]]) – A sequence of iid integer multinomial observations in the form of Sequence of Tuple(s) containing integer-category and float valued number of successes.

Returns:

Tuple[int, ndarray[int], ndarray[float], ndarray[int], Optional[T]. See above for details.

Return type:

tuple[int, ndarray, ndarray, ndarray, Any | None]