mixle.stats.multivariate.integer_multinomial module¶

Evaluate, estimate, and sample from a integer multinomial distribution on range [min_val, max_val].

Defines the IntegerMultinomialDistribution, IntegerMultinomialSampler, IntegerMultinomialAccumulatorFactory, IntegerMultinomialAccumulator, IntegerMultinomialEstimator, and the IntegerMultinomialDataEncoder classes for use with mixle.

Data type: Sequence[Tuple[int, float]]: Consider an observation of a multinomial consisting of integer-category counts of the form x = (x_0,..,x_K), where K is the number of integers in the range [min_val, max_val]. The IntegerMultinomialDistribution with support [min_val, max_value], number of trials ‘N’, and probability of success for the integer-categories given by p = (p_0, …, p_k), scores the un-normalized 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)[source]

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()[source]

compute_declaration()[source]

static exp_family_sufficient_statistics(x, engine)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Create an IntegerMultinomialSampler object for sampling from integer multinomial.

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

estimator(pseudo_count=None)[source]

Create and IntegerMultinomialEstimator object for estimating IntegerMultinomialDistribution from aggregated: sufficient statistics.

Parameters:: pseudo_count (Optional[float]) – Used to re-weight sufficient statistics of object instance when estimated.
Returns:: IntegerMultinomialEstimator object.
Return type:: IntegerMultinomialEstimator

dist_to_encoder()[source]

Returns IntegerMultinomialDataEncoder object with len_encoder created from len_dist.

Return type:: IntegerMultinomialDataEncoder

enumerator()[source]

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

Return type:: IntegerMultinomialEnumerator

class IntegerMultinomialEnumerator(dist)[source]

Bases: DistributionEnumerator

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

Parameters:: dist (IntegerMultinomialDistribution)

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

Bases: DistributionSampler

Parameters:

dist (IntegerMultinomialDistribution)
seed (int | None)

sample(size=None)[source]

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())[source]

Bases: SequenceEncodableStatisticAccumulator

Parameters:

min_val (int | None)
max_val (int | None)
name (str | None)
keys (str | None)
len_accumulator (SequenceEncodableStatisticAccumulator | None)

update(x, weight, estimate)[source]

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)[source]

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 RandomState object for consistency with SequenceEncodableStatisticAccumulator class.

Returns:

None.

Return type:

None

seq_update(x, weights, estimate)[source]

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)[source]

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)[source]

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

Note: Just calls seq_update() method.

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 RandomState object for consistency with SequenceEncodableStatisticAccumulator class.

Returns:

None.

Return type:

None

combine(suff_stat)[source]

Combine sufficient statistics in arg ‘suff_stat’ with sufficient statistics of obejct instance.

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()[source]

Returns sufficient statistics ‘suff_stat’ of object instance..

Return value ‘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.

Returns:: Tuple[int, ndarray, Optional[SS0]].
Return type:: tuple[int, ndarray, Any | None]

from_value(x)[source]

Sets the object instance sufficient statistics to value of arg ‘x’.

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

Parameters:: x (See above for details)
Returns:: IntegerMultinomialAccumulator object.
Return type:: IntegerMultinomialAccumulator

key_merge(stats_dict)[source]

Merge sufficient statistics of object instance with objects of matching key contained in stats_dict.

Parameters:: stats_dict (Dict[str, Any]) – Dictionary with keys for merging sufficient statistics of matching key sufficient statistics.
Returns:: None.
Return type:: None

key_replace(stats_dict)[source]

Replace sufficient statistics of object instance with sufficient statistics in arg ‘stats_dict’ of matching: keys.

Parameters:: stats_dict (Dict[str, Any]) – Dictionary with keys for merging sufficient statistics of matching key sufficient statistics.
Returns:: None.
Return type:: None

acc_to_encoder()[source]

Returns IntegerMultinomialDataEncoder object with len_encoder created from len_accumulator.

Return type:: IntegerMultinomialDataEncoder

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

Bases: StatisticAccumulatorFactory

Parameters:

min_val (int | None)
max_val (int | None)
name (str | None)
keys (str | None)
len_factory (StatisticAccumulatorFactory | None)

make()[source]

Returns IntegerMultinomialAccumulator object for

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)[source]

Bases: ParameterEstimator

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()[source]

Create an IntegerMultinomialAccumulatorFactory object from IntegerMultinomialEstimator object instance.

Return type:: IntegerMultinomialAccumulatorFactory

estimate(nobs, suff_stat)[source]

Estimate an IntegerMultinomialDistribution from aggregated sufficient statistics in arg ‘suff_stat’.

Note: If pseudo_count is not set, member sufficient statistics are ignored in estimation.

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:

nobs (Optional[float]) – Number of observations in accumulated data.
suff_stat (tuple[int, ndarray, SS0 | None]) – See above for details.

Returns:

IntegerMultinomialDistribution object.

Return type:

IntegerMultinomialDistribution

class IntegerMultinomialDataEncoder(len_encoder=NullDataEncoder())[source]

Bases: DataSequenceEncoder

Parameters:: len_encoder (DataSequenceEncoder | None)

seq_encode(x)[source]

Encode a sequence of iid integer multinomial observations.

Returns 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. 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]