mixle.stats.combinator.composite module

Independent product distributions over tuple-valued observations.

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

Return compute-backend metadata shared by all component distributions.

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

Return the symbolic declaration for the product of component distributions.

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

Return joined density semantics over all component distributions.

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)

Return a sampler that samples each component independently.

Parameters:

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

Returns:

CompositeSampler object.

Return type:

CompositeSampler

estimator(pseudo_count=None)

Return a composite estimator built from the component estimators.

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

Return a tuple encoder assembled from the component encoders.

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

Best-first enumerator over the Cartesian product of component supports.

Parameters:

dist (CompositeDistribution)

class CompositeConditionalEnumerator(dist, given)

Bases: DistributionEnumerator

Best-first enumerator for complete tuples consistent with fixed component values.

Parameters:

• dist (CompositeDistribution)

• given (dict[int, Any])

class CompositeSampler(dist, seed=None)

Bases: DistributionSampler

Sampler that draws each component independently from its own sampler.

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

Accumulator that delegates sufficient-statistic updates to component accumulators.

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 low-level sequence kernels from all component accumulators.

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

Return one sufficient-statistic value per component accumulator.

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

Return a tuple encoder assembled from the child accumulator encoders.

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

Returns:

CompositeDataEncoder

Return type:

CompositeDataEncoder

class CompositeAccumulatorFactory(factories, keys=None)

Bases: StatisticAccumulatorFactory

Factory for composite accumulators built from component accumulator factories.

Parameters:

• factories (Sequence[StatisticAccumulatorFactory])

• keys (str | None)

make()

Create a composite accumulator from the component factories.

Returns:

CompositeAccumulator

Return type:

CompositeAccumulator

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

Bases: ParameterEstimator

Estimator that fits each independent component distribution from its own statistics.

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

Return an accumulator factory assembled from the child estimators.

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

Encoder that applies each component encoder to the corresponding tuple field.

Parameters:

encoders (Sequence[DataSequenceEncoder])

seq_encode(x)

Encode tuple-valued observations for vectorized seq_* methods.

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

Fisher view that concatenates component sufficient-statistic vectors.

Parameters:

dist (Any)