mixle.stats.combinator.composite module

Create, estimate, and sample from a Composite distribution.

Defines the CompositeDistribution, CompositeSampler, CompositeAccumulatorFactory, CompositeAccumulator, CompositeEstimator, and the CompositeDataEncoder classes for use with mixle.

Data type: (Tuple[T_0, … T_{n-1}]): The CompositeDistribution of size ‘n’ is a joint distribution for independent observations of ‘n’-tupled data. Each component ‘k’ of the CompositeDistribution has data type T_k that must be compatible with data type T_k.

class CompositeDistribution(dists, prior=None)

Bases: SequenceEncodableProbabilityDistribution

Product distribution over heterogeneous component variables.

Parameters:

• dists (Sequence[SequenceEncodableProbabilityDistribution])

• prior (Sequence[SequenceEncodableProbabilityDistribution] | None)

compute_capabilities()

get_prior()

Return the joint prior as the list of per-component child priors (in component order).

Return type:

list[SequenceEncodableProbabilityDistribution | None]

set_prior(prior)

Distribute per-component parameter priors to the wrapped child distributions.

CompositeDistribution owns no parameters of its own; the joint prior factors over the independent components. prior=None is a no-op (children keep their existing priors, leaving the MLE path byte-identical); otherwise prior must be a sequence of exactly count child priors that are pushed to the children via their own set_prior.

Parameters:

prior (Sequence[SequenceEncodableProbabilityDistribution | None] | None)

Return type:

None

expected_log_density(x)

Prior-expected log-density: sum of the component expected_log_density values at x.

Parameters:

x (tuple[Any, ...])

Return type:

float

seq_expected_log_density(x)

Vectorized prior-expected log-density: sum of the component seq_expected_log_density values.

Parameters:

x (E)

Return type:

ndarray

compute_declaration()

marginal(indices)

The marginal sub-composite over the given component indices.

Because the components are independent, the marginal of a subset of coordinates is just the sub-product over those coordinates. Used (with condition()) by MixtureDistribution.conditional to score the observed coordinates of a partial observation.

Parameters:

indices (Sequence[int])

Return type:

CompositeDistribution

condition(observed)

The conditional sub-composite over the UNobserved components given observed.

observed maps a component index to its (present) value. Since the components are independent, conditioning leaves the unobserved factors unchanged – the conditional is the sub-product over the coordinates not in observed (the observed values do not enter). This is the per-component piece that makes MixtureDistribution.conditional return the posterior/imputation over the missing fields of a partial observation.

Parameters:

observed (dict[int, Any])

Return type:

CompositeDistribution

density(x)

Evaluates density of CompositeDistribution for single observation tuple x.

p_mat(x) = p_mat(x_0 | dist_0)*p_mat(x_1 | dist_1)*…*p_mat(x_{n-1} | dist_{n-1}),

where dist_k is the k^{th} element of member variable dists and is consistent with data type type(x[k]).

Parameters:

x (Tuple[Any, ...]) – Tuple of length = len(dists), the k^{th} data type must be consistent with dists[k].

Returns:

Density as float.

Return type:

float

density_semantics()

What log_density returns relative to the true log-density (default: exact).

Override to declare that this distribution’s log_density is a variational lower bound (ELBO), an upper bound, or an approximation rather than the exact log p(x). This is surfaced as the ExactDensity capability and noted in mixle.describe(), so code that needs an exact likelihood can require(x, ExactDensity) instead of silently trusting a bound.

log_density(x)

Evaluates log-density of CompositeDistribution for single observation tuple x.

log(p_mat(x)) = log(p_mat(x_0 | dist_0)) + log(p_mat(x_1 | dist_1)) + … + log(p_mat(x_{n-1} | dist_{n-1})),

where dist_k is the k^{th} element of member variable dists and is consistent with data type type(x[k]).

Parameters:

x (Tuple[Any, ...]) – Tuple of length = len(dists), the k^{th} data type must be consistent with dists[k].

Returns:

Log-density as float.

Return type:

float

seq_log_density(x)

Vectorized evaluation of log density for Tuple of dist encoded data.

Each entry of x is an encoded sequence, encoded by the DataSequenceEncoder of dist[k].dist_to_encoder().

Note: len(x) == len(dists). :param x: Tuple of length = len(dists), with k^{th} entry given by encoded sequence of dist[k]’s. :type x: E

Returns:

np.ndarray of log_density evaluated at all encoded data points.

Parameters:

x (E)

Return type:

ndarray

backend_seq_log_density(x, engine)

Engine-neutral vectorized log-density by composing child distributions.

Parameters:

• x (E)

• engine (Any)

Return type:

Any

gradient_fit_state(engine, torch, leaves, recurse, tensor_param)

Return distribution-owned state for autograd fitting.

Parameters:

• engine (Any)

• torch (Any)

• leaves (list[Any])

• recurse (Any)

• tensor_param (Any)

Return type:

Any

classmethod backend_stacked_params(dists, engine)

Return stacked child parameters for homogeneous composite mixtures.

Parameters:

• dists (Sequence[CompositeDistribution])

• engine (Any)

Return type:

dict[str, Any]

classmethod backend_stacked_log_density(x, params, engine)

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

Parameters:

• x (E)

• 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 composite sufficient statistics.

Parameters:

• x (E)

• weights (Any)

• params (dict[str, Any])

• engine (Any)

• estimator (Any)

Return type:

tuple[Any, …]

support_size()

Product of child support sizes (None if any child is infinite).

Return type:

int | None

to_fisher(**kwargs)

Structural Fisher view (product of child views).

to_exponential_family(engine=None)

Return the product exponential-family view, or None.

A composite is an exponential family iff every child is: the canonical pieces concatenate (eta, T) and add (A, log h). Returns None when any child is not a (single) exponential family.

Parameters:

engine (Any)

sampler(seed=None)

Create CompositeSampler for sampling from CompositeDistribution instance.

Parameters:

seed (Optional[int]) – Seed to set for sampling with RandomState.

Returns:

CompositeSampler object.

Return type:

CompositeSampler

estimator(pseudo_count=None)

Create CompositeEstimator for estimating CompositeDistribution.

Parameters:

pseudo_count (Optional[float]) – Used to inflate sufficient statistics in estimation.

Returns:

CompositeEstimator object.

Return type:

CompositeEstimator

decomposition()

Composite factors are independent: split along the factor axis, sufficient stats SUM-reduce.

dist_to_encoder()

Creates CompositeDataEncoder for encoding sequence of tuple data.

Passes ‘encoders’, which is a list of DataSequenceEncoders for each component of the CompositeDistribution.

Returns:

CompositeDataEncoder object.

Return type:

CompositeDataEncoder

enumerator()

Creates CompositeEnumerator iterating tuples in descending joint probability order.

Return type:

CompositeEnumerator

conditional_enumerator(given)

Enumerate complete tuples consistent with the fixed positions in given, best-first.

given is a mapping {position: value} pinning a subset of coordinates (most-probable completion / imputation). Because the components are independent, descending order over the free coordinates is descending conditional order; each yielded tuple has the fixed positions filled in and carries the full joint log_density (the fixed positions are a constant offset). Raises ValueError for an out-of-range position.

Parameters:

given (Mapping[int, Any])

Return type:

CompositeConditionalEnumerator

quantized_index(max_bits, bin_width_bits=1.0)

Build a bounded index with a DP over additive quantized child costs.

Each child item is assigned an integer cost ceil(bits/bin_width_bits). The composite cost is the sum of those integer costs, so the bin counts are a convolution of child cost-bin counts. Items are unranked lazily from the child bin offsets when requested; the returned log probability is still the exact joint log-density.

Parameters:

• max_bits (float)

• bin_width_bits (float)

Return type:

LazyQuantizedEnumerationIndex

structural_fine_bucket(value, quantizer)

Sum of child structural buckets – mirrors the count index’s child convolution.

Return type:

int

quantized_count_index(quantizer, max_fine_bucket)

Structural count index: the ADDITIVE law – the carrier’s n-ary product over children.

The complete log density is the sum of independent child log densities, so the joint count histogram is the times/product (convolution) of the child histograms in the witness-retaining count semiring (mixle.enumeration.quantization.semiring). Children are consumed by their counts and lazy unranker – never drained – so a child with astronomically large support (e.g. a Sequence) composes without being materialized. Swapping the carrier (e.g. a tropical one) would reuse this same reduction.

Parameters:

max_fine_bucket (int)

quantized_multi_cross_index(others, max_bits, bin_width_bits=1.0)

Build an aligned cross-bin view for compatible composite distributions.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

quantized_cross_index(other, max_bits, bin_width_bits=1.0)

Build an aligned cross-bin view for two compatible composite distributions.

Parameters:

bin_width_bits (float)

Return type:

QuantizedCrossIndex

class CompositeEnumerator(dist)

Bases: DistributionEnumerator

Parameters:

dist (CompositeDistribution)

class CompositeConditionalEnumerator(dist, given)

Bases: DistributionEnumerator

Parameters:

• dist (CompositeDistribution)

• given (dict[int, Any])

class CompositeSampler(dist, seed=None)

Bases: DistributionSampler

Parameters:

• dist (CompositeDistribution)

• seed (int | None)

sample(size=None)

Generate independent samples from a CompositeDistribution.

If size is None, draw one sample and return as Tuple of length = len(dists). If size > 0, draw size samples and return a list of length size containing tuples of len(dists).

Parameters:

size (Optional[int]) – If None, draw 1 sample. Else, draw size number of iid samples.

Returns:

A tuple of length = len(dists) or a list of length size containing tuples of length = len(dists).

Return type:

list[tuple[Any, …]] | tuple[Any, …]

class CompositeAccumulator(accumulators, keys=None)

Bases: SequenceEncodableStatisticAccumulator

Parameters:

• accumulators (Sequence[SequenceEncodableStatisticAccumulator])

• keys (str | None)

update(x, weight, estimate)

Calls update on each CompositeAccumulator component[k], passing x[k] and weight along with estimate

if provided.

Component-wise update() calls to accumulator for each component of x. The same weight is passed to each update call, along with the corresponded component-distribution estimate, if estimate is provided.

Parameters:

• x (Any) – Category label.

• weight (float) – Weight for the observation x.

• estimate (Optional['CategoricalDistribution']) – Kept for consistency with update method in SequenceEncodableStatisticAccumulator.

Returns:

None

Return type:

None

initialize(x, weight, rng)

Initialize each accumulator of CompositeAccumulator with component x[i] of x and weight.

Note: rng is used to set List[RandomState]: _acc_rng. This is done to ensure iteration over observations of data, produces the same initialization as seq_initialize().

Parameters:

• x (Tuple[Any, ...]) – Observation Tuple of length count, that is component-wise compatible with CompositeAccumulator member variable accumulators.

• weight (float) – Weight for the observation x.

• rng (RandomState) – Used to set seed of _acc_rng if not set.

Returns:

None

Return type:

None

seq_initialize(x, weights, rng)

Vectorized initialization of each accumulator of CompositeAccumulator with encoded data x.

Note: rng is used to set List[RandomState]: _acc_rng. This is done to ensure iteration over observations of data, produces the same initialization as seq_initialize().

Parameters:

• x (E) – Tuple of component wise sequence encoding of data.

• weights (np.ndarray) – Numpy array weights for the encoded observations.

• rng (RandomState) – Used to set seed of _acc_rng if not set.

Returns:

None

Return type:

None

get_seq_lambda()

Return type:

list[Any]

seq_update(x, weights, estimate)

Vectorized aggregation of sufficient statistics for each component of CompositeAccumulator.

Requires sequence encoded input x, from CompositeDataEncoder.seq_encode(data).

Parameters:

• x (Tuple[Any, ...]) – Encoded sequence Tuple of length count, that is a component wise sequence encoding of data.

• weights (np.ndarray) – Numpy array weights for the encoded observations.

• estimate (CompositeDistribution | None)

Returns:

None.

Return type:

None

seq_update_engine(x, weights, estimate, engine)

Engine-resident E-step: route each component accumulator through the active engine so nested families stay resident. Matches seq_update.

Parameters:

• x (tuple[Any, ...])

• weights (Any)

• estimate (CompositeDistribution | None)

• engine (Any)

Return type:

None

combine(suff_stat)

Aggregate the sufficient statistics of CompositeAccumulator with input suff_stat.

Parameters:

suff_stat (SS) – Tuple of sufficient statistics for each component of the CompositeAccumulator.

Returns:

None

Return type:

CompositeAccumulator

value()

Returns Tuple of length equal to member variable count, containing sufficient statistics for each component.

Return type:

tuple[Any, …]

from_value(x)

Set CompositeAccumulator instance sufficient statistics to x.

Parameters:

x (SS) – Tuple of length equal to member variable count, containing sufficient statistics for each component.

Returns:

CompositeAccumulator

Return type:

CompositeAccumulator

scale(c)

Scale each child accumulator using its family-specific protocol.

Parameters:

c (float)

Return type:

CompositeAccumulator

key_merge(stats_dict)

Combines the sufficient statistics of CompositeAccumulators that have the same key value.

If key is not in the stats_dict (dictionary), the key and accumulator are added to the dict.

Parameters:

stats_dict (Dict[str, Any]) – Dictionary for mapping keys to CompositeAccumulators.

Returns:

None

Return type:

None

key_replace(stats_dict)

Set CompositeAccumulator sufficient statistic attributes values to suff stats with matching keys.

Parameters:

stats_dict (Dict[str, Any]) – Maps member variable key to CompositeAccumulator with same key.

Returns:

None

Return type:

None

acc_to_encoder()

Creates CompositeDataEncoder for encoding sequence of tuple data.

encoders is a list of DataSequenceEncoders for each component of the CompositeDistribution.

Returns:

CompositeDataEncoder

Return type:

CompositeDataEncoder

class CompositeAccumulatorFactory(factories, keys=None)

Bases: StatisticAccumulatorFactory

Parameters:

• factories (Sequence[StatisticAccumulatorFactory])

• keys (str | None)

make()

Create a CompositeAccumulator object from list of StatisticAccumulatorFactory objects.

Returns:

CompositeAccumulator

Return type:

CompositeAccumulator

class CompositeEstimator(estimators, keys=None, prior=None)

Bases: ParameterEstimator

Parameters:

• estimators (Sequence[ParameterEstimator])

• keys (str | None)

• prior (Sequence[Any] | None)

get_prior()

Return the joint prior as the list of per-component child estimator priors (in order).

Return type:

list[Any]

set_prior(prior)

Distribute per-component parameter priors to the child estimators.

prior=None is a no-op (children keep their existing priors). Otherwise prior must be a sequence of exactly count priors pushed to the children via their own set_prior.

Parameters:

prior (Sequence[Any] | None)

Return type:

None

model_log_density(model)

Sum the child estimators’ model_log_density on the corresponding child models (ELBO global term).

Parameters:

model (CompositeDistribution)

Return type:

float

accumulator_factory()

Creates CompositeAccumulatorFactory from each ParameterEstimator in estimators.

Returns:

CompositeAccumulatorFactory.

Return type:

CompositeAccumulatorFactory

estimate(nobs, suff_stat)

Estimate a CompositeDistribution from an aggregated sufficient statistics Tuple for a given number of

observations (nobs).

Parameters:

• nobs (Optional[float]) – Weighted number of observations used to form suff_stat.

• suff_stat (SS) – Tuple of sufficient statistics for each ParameterEstimator of estimators.

Returns:

CompositeDistribution estimated from argument aggregated sufficient statistics (suff_stat), from a given

number of observation (nobs).

Return type:

CompositeDistribution

class CompositeDataEncoder(encoders)

Bases: DataSequenceEncoder

Parameters:

encoders (Sequence[DataSequenceEncoder])

seq_encode(x)

Encode Sequence of tuples of data for use with vectorized “seq_” functions.

The input x must be a Sequence of Tuples of length equal to the length of encoders. Each component tuple observation of x, say x[i], must be component-wise compatible with encoders.

Parameters:

x (Sequence[Tuple[Any, ...]]) – Sequence of tuples of length equal to len(encoders).

Returns:

Tuple of length equal to len(encoders), with entry i, containing the sequence encoding from encoder[i] for all observations of component i from x.

Return type:

tuple[Any, …]

class CompositeFisherView(dist)

Bases: FixedFisherView

Parameters:

dist (Any)