mixle.stats.univariate.discrete.integer_categorical module

Integer-categorical distributions over consecutive bounded supports.

The observation type is int. A distribution is parameterized by min_val and a probability vector p_vec whose entries correspond to values min_val, min_val + 1, ..., min_val + len(p_vec) - 1. Values outside that range have zero probability.

class IntegerCategoricalFisherView(dist)

Bases: CategoricalFisherView

Fisher view for bounded integer-categorical one-hot statistics.

Parameters:

dist (Any)

class IntegerCategoricalDistribution(min_val, p_vec=MISSING, name=None, prob_vec=MISSING, prior=None)

Bases: SequenceEncodableProbabilityDistribution

Categorical distribution over a bounded integer range.

Parameters:

• min_val (int)

• p_vec (list[float] | ndarray)

• name (str | None)

• prob_vec (list[float] | ndarray)

• prior (SequenceEncodableProbabilityDistribution | None)

classmethod compute_capabilities()

Return compute-backend metadata for integer-categorical scoring.

classmethod compute_declaration()

Return the symbolic declaration for bounded integer-categorical probabilities.

static exp_family_sufficient_statistics(x, engine)

Return raw values; category-aware one-hot statistics 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 one-hot category indicator T(x) of shape (n, K) (zeros off support).

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(x) = 0 on the support [min_val, min_val+K) and -inf outside it.

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

get_parameters()

Return the probability vector p_vec (lets it be scored by a Dirichlet conjugate prior).

Return type:

ndarray

get_prior()

Return the conjugate parameter prior over the probability vector (or None).

Return type:

SequenceEncodableProbabilityDistribution | None

set_prior(prior)

Attach a parameter prior and precompute conjugate-prior expectations.

With a Dirichlet(alpha) (or SymmetricDirichlet(alpha)) prior over the probability vector this caches the variational expected log-probabilities E[log p_k] = digamma(alpha_k) - digamma(sum_k alpha_k) so that expected_log_density(x) = E[log p_{x - min_val}] - log(1 + default_value). Any other prior (including None) leaves the distribution a plain point model.

Parameters:

prior (SequenceEncodableProbabilityDistribution | None)

Return type:

None

expected_log_density(x)

Variational expectation E_q[log p(x)] under the (symmetric) Dirichlet prior.

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)

Vectorized expected_log_density over sequence-encoded observations.

Parameters:

x (ndarray)

Return type:

ndarray

density(x)

Evaluate the density of the integer categorical at observation x.

p_mat(x_mat=x) = p_vec[x] if x in support [min_val, max_val], else 0.0.

Parameters:

x (int) – Integer value.

Returns:

Density at x.

Return type:

float

log_density(x)

Evaluate the log-density of the integer categorical at observation x.

log_p(x_mat=x) = log_p_vec[x] if x in support [min_val, max_val], else -np.inf.

Parameters:

x (int) – Integer value.

Returns:

Log-density at x.

Return type:

float

seq_log_density(x)

Vectorized evaluation of IntegerCategorical log_density() for sequence encoded iid observations x.

Parameters:

x (np.ndarray[int]) – Sequence encoded iid observation of integer categorical distribution.

Returns:

Numpy array of floats containing log_density() evaluated at each observation in x.

Return type:

ndarray

static backend_log_density_from_params(x, min_val, log_p_vec, engine)

Engine-neutral integer-categorical log-density from explicit parameters.

Parameters:

• x (Any)

• min_val (int)

• log_p_vec (Any)

• engine (Any)

Return type:

Any

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density for encoded data.

Parameters:

• x (Any)

• engine (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked integer-categorical parameters for a homogeneous mixture kernel.

Parameters:

• dists (Sequence[IntegerCategoricalDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

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

Parameters:

• x (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

Any

classmethod backend_stacked_sufficient_statistics(x, weights, params, engine)

Return component-stacked legacy (min_val, count_vec) statistics.

Parameters:

• x (Any)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

Return type:

tuple[Any, Any]

support_size()

Number of integer values in the range.

Return type:

int

to_fisher(**kwargs)

Return the integer-categorical one-hot Fisher view.

sampler(seed=None)

Return a sampler for iid draws from this distribution.

Parameters:

seed (int | None) – Optional random seed.

Return type:

IntegerCategoricalSampler

estimator(pseudo_count=None)

Return an estimator initialized from this distribution.

When pseudo_count is provided, the distribution’s probabilities are used as prior sufficient statistics during estimation.

Parameters:

pseudo_count (float | None) – Weight assigned to the distribution’s current probability vector during estimation.

Return type:

IntegerCategoricalEstimator

dist_to_encoder()

Return the encoder for iid integer categorical observations.

Return type:

IntegerCategoricalDataEncoder

enumerator()

Return IntegerCategoricalEnumerator iterating the support in descending probability order.

Return type:

IntegerCategoricalEnumerator

quantized_index(max_bits, bin_width_bits=1.0)

Build a bounded bit-quantized index directly from the finite integer support.

Parameters:

• max_bits (float)

• bin_width_bits (float)

Return type:

QuantizedEnumerationIndex

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)

Build an exact aligned cross-bin view over integer categorical ranges.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)

Build an exact aligned cross-bin view over two integer categorical ranges.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

class IntegerCategoricalEnumerator(dist)

Bases: DistributionEnumerator

Enumerator over bounded integer support in descending probability order.

Parameters:

dist (IntegerCategoricalDistribution)

class IntegerCategoricalSampler(dist, seed=None)

Bases: DistributionSampler

Sampler for bounded integer-categorical values.

Parameters:

• dist (IntegerCategoricalDistribution)

• seed (int | None)

sample(size=None)

Draw iid samples from the integer-categorical distribution.

Parameters:

size (int | None) – Number of samples. None returns one integer; a positive value returns a list of that length.

Return type:

int | list[int]

class IntegerCategoricalAccumulator(min_val=None, max_val=None, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulator for weighted counts over a bounded integer support.

Parameters:

• min_val (int | None)

• max_val (int | None)

• keys (str | None)

update(x, weight, estimate)

Update sufficient statistics with one weighted observation.

If the observed value falls outside the current support, the count vector is expanded and existing counts are realigned.

Parameters:

• x (int) – Integer observation.

• weight (float) – Observation weight.

• estimate (IntegerCategoricalDistribution | None) – Accepted for accumulator API consistency.

Return type:

None

initialize(x, weight, rng)

Initialize sufficient statistics with one weighted observation.

Parameters:

• x (int) – Integer observation.

• weight (float) – Observation weight.

• rng (RandomState) – Accepted for accumulator API consistency.

Returns:

None.

Return type:

None

seq_initialize(x, weights, rng)

Vectorized initialization of IntegerCategoricalAccumulator sufficient statistics with weighted observations.

This delegates to seq_update().

Parameters:

• x (np.ndarray[int]) – Sequence encoded iid observations of integer categorical distribution.

• weights (ndarray) – Numpy array of positive floats.

• rng (Optional[RandomState]) – Kept for consistency with SequenceEncodableStatisticAccumulator.

Returns:

None.

Return type:

None

seq_update(x, weights, estimate)

Vectorized update of IntegerCategoricalAccumulator sufficient statistics with sequence encoded iid

observations x.

Note: Determines the range (support) of integer categorical from the sequence encoded data.

Parameters:

• x (np.ndarray[int]) – Sequence encoded iid observations of integer categorical distribution.

• weights (ndarray) – Numpy array of positive floats.

• estimate (Optional[IntegerCategoricalDistribution]) – Previous estimate of IntegerCategoricalDistribution.

Returns:

None.

Return type:

None

seq_update_engine(x, weights, estimate, engine)

Engine-resident accumulation: the weighted value histogram is reduced on the active engine (numpy or torch); the dynamic support range is host bookkeeping. Matches seq_update.

Parameters:

• x (ndarray)

• weights (Any)

• estimate (IntegerCategoricalDistribution | None)

• engine (Any)

Return type:

None

combine(suff_stat)

Merge another (min_val, count_vec) sufficient statistic.

Supports are aligned before counts are added, so accumulators built on different observed ranges can be combined safely.

Parameters:

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

Return type:

IntegerCategoricalAccumulator

value()

Return (min_val, count_vec) sufficient statistics.

Return type:

tuple[int, ndarray]

from_value(x)

Replace accumulator state from a (min_val, count_vec) statistic.

Parameters:

x (tuple[int, ndarray])

Return type:

IntegerCategoricalAccumulator

scale(c)

Scale count vector while preserving integer support metadata.

Parameters:

c (float)

Return type:

IntegerCategoricalAccumulator

key_merge(stats_dict)

Aggregate member sufficient statistics with sufficient statistics of objects with matching keys.

Parameters:

stats_dict (Dict[str, Any]) – Dict mapping keys to corresponding sufficient stats.

Returns:

None.

Return type:

None

key_replace(stats_dict)

Set member sufficient statistics to suff stats with matching keys.

Parameters:

stats_dict (Dict[str, Any]) – Dict mapping keys to corresponding sufficient stats.

Returns:

None.

Return type:

None

acc_to_encoder()

Return the encoder associated with this accumulator.

Return type:

IntegerCategoricalDataEncoder

class IntegerCategoricalAccumulatorFactory(min_val=None, max_val=None, keys=None)

Bases: StatisticAccumulatorFactory

Factory for integer-categorical count accumulators.

Parameters:

• min_val (int | None)

• max_val (int | None)

• keys (str | None)

make()

Return a fresh integer categorical accumulator with this factory’s bounds and keys.

Return type:

IntegerCategoricalAccumulator

class IntegerCategoricalEstimator(min_val=None, max_val=None, pseudo_count=None, suff_stat=None, name=None, keys=None, prior=None)

Bases: ParameterEstimator

Estimator for bounded integer-categorical probability vectors.

Parameters:

• min_val (int | None)

• max_val (int | None)

• pseudo_count (float | None)

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

• name (str | None)

• keys (str | None)

• prior (SequenceEncodableProbabilityDistribution | None)

get_prior()

Return the conjugate parameter prior over the probability vector (or None).

Return type:

SequenceEncodableProbabilityDistribution | None

set_prior(prior)

Set the conjugate parameter prior over the probability vector.

Parameters:

prior (SequenceEncodableProbabilityDistribution | None)

Return type:

None

model_log_density(model)

Log-density of the model probability vector under the (symmetric) Dirichlet prior.

Parameters:

model (IntegerCategoricalDistribution)

Return type:

float

accumulator_factory()

Return an accumulator factory configured from this estimator’s support and keys.

Note: If min_val and max_val are BOTH not None, these values are passed to IntegerCategoricalAccumulatorFactory. Else, they are obtained from member variable suff_stat. One of these conditions must be satisfied.

Returns:

Return type:

IntegerCategoricalAccumulatorFactory

estimate(nobs, suff_stat)

Estimate an integer-categorical distribution from weighted counts.

nobs is accepted for estimator API consistency but is not used. suff_stat is (min_val, count_vec). When pseudo_count and a prior statistic are present, the estimate combines observed counts with the weighted prior probability vector.

Parameters:

• nobs (float | None)

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

Return type:

IntegerCategoricalDistribution

class IntegerCategoricalDataEncoder

Bases: DataSequenceEncoder

Data encoder for iid integer-categorical observations.

seq_encode(x)

Sequence encode iid integer categorical observations for “seq_” functions.

Parameters:

x (Union[List[int], np.ndarray]) – Assumed int observations of integer categorical.

Returns:

Numpy array of integers.

Return type:

ndarray