mixle.stats.trees.chow_liu_tree module

Generic Chow-Liu tree distribution for fixed-length tuple observations.

The integer-only mixle.stats.trees.integer_chow_liu_tree implementation uses dense integer count tables. This module keeps the Chow-Liu structure learning step generic: parent variables are represented by their observed/enumerable values, while each child conditional distribution is estimated with the user-supplied estimator for that coordinate.

Data type: Sequence[Any] with fixed length.

class ChowLiuTreeDistribution(parents, marginal_dists, conditional_dists, default_dists=None, feature_order=None, parent_values=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Chow-Liu tree over fixed-position fields with generic conditional models.

parents[i] gives the parent feature of feature i; exactly one entry must be None and is treated as the root. The root uses its marginal distribution. Non-root features use conditional_dists[i][freeze(x[parent])] when present, otherwise default_dists[i] if one was supplied.

Parameters:
compute_capabilities()[source]
compute_declaration()[source]
density(x)[source]

Return the probability density or mass at a single observation.

Parameters:

x (Sequence[Any])

Return type:

float

conditional_dist(child, parent_value)[source]

Return the conditional distribution associated with a child and parent assignment.

Parameters:

  • child (int)

  • parent_value (Any)

Return type:

SequenceEncodableProbabilityDistribution | None

log_density(x)[source]

Return the log-density or log-mass at a single observation.

Parameters:

x (Sequence[Any])

Return type:

float

seq_log_density(x)[source]

Return vectorized log-density values for sequence-encoded observations.

Parameters:

x (Sequence[Sequence[Any]])

Return type:

ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral grouped scoring for fixed Chow-Liu tree factors.

Parameters:
Return type:

Any

sampler(seed=None)[source]

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

ChowLiuTreeSampler

estimator(pseudo_count=None)[source]

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

ChowLiuTreeEstimator

dist_to_encoder()[source]

Return the data encoder used by this distribution for vectorized methods.

Return type:

ChowLiuTreeDataEncoder

enumerator()[source]

Return an enumerator over the distribution support when available.

Return type:

ChowLiuTreeEnumerator

class ChowLiuTreeEnumerator(dist)[source]

Bases: DistributionEnumerator

Finite-support enumerator for a ChowLiuTreeDistribution.

Parameters:

dist (ChowLiuTreeDistribution)

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

Bases: DistributionSampler

Sampler for a generic Chow-Liu tree.

Parameters:

  • dist (ChowLiuTreeDistribution)

  • seed (int | None)

sample(size=None)[source]

Draw observations.

Combinator samplers (mixture/sequence/…) accept batched. With batched=True (the default) each child stream is drawn in one vectorized call instead of a per-draw Python loop – far faster. Because every child sampler owns an independent RandomState, batching consumes each stream in the same order as the loop, so the draws are identical to the legacy path. batched=False forces that legacy per-draw loop as a guaranteed- stable reference. Leaf samplers are already vectorized and ignore the flag.

Parameters:

size (int | None)

Return type:

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

class ChowLiuTreeAccumulator(estimators, keys=None, name=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulator for generic Chow-Liu tree sufficient statistics.

Parameters:

  • estimators (Sequence[ParameterEstimator])

  • keys (str | None)

  • name (str | None)

update(x, weight, estimate)[source]
Parameters:
Return type:

None

initialize(x, weight, rng)[source]
Parameters:
Return type:

None

seq_update(x, weights, estimate)[source]
Parameters:
Return type:

None

seq_initialize(x, weights, rng)[source]
Parameters:
Return type:

None

combine(suff_stat)[source]
Parameters:

suff_stat (tuple[float, int, list[dict[Hashable, float]], list[dict[Hashable, Any]], dict[tuple[int, int], dict[tuple[Hashable, Hashable], float]], tuple[Any, ...], dict[tuple[int, int], dict[Hashable, Any]]])

Return type:

ChowLiuTreeAccumulator

value()[source]
Return type:

tuple[float, int, list[dict[Hashable, float]], list[dict[Hashable, Any]], dict[tuple[int, int], dict[tuple[Hashable, Hashable], float]], tuple[Any, …], dict[tuple[int, int], dict[Hashable, Any]]]

from_value(x)[source]
Parameters:

x (tuple[float, int, list[dict[Hashable, float]], list[dict[Hashable, Any]], dict[tuple[int, int], dict[tuple[Hashable, Hashable], float]], tuple[Any, ...], dict[tuple[int, int], dict[Hashable, Any]]])

Return type:

ChowLiuTreeAccumulator

scale(c)[source]

Scale linear sufficient statistics in-place by c.

The structural default is correct for ordinary weighted sums, nested tuples/lists/dicts, and numeric arrays. Families whose value() payload includes non-linear metadata such as support bounds must override this method and leave that metadata unscaled.

Parameters:

c (float)

Return type:

ChowLiuTreeAccumulator

key_merge(stats_dict)[source]

Pool this accumulator’s statistics into stats_dict under its merge key.

The structural default implements the common single-key pattern: store the accumulator under self.keys the first time the key is seen, else combine into the one already there. Accumulators with several named keys (e.g. an HMM’s init/trans/state keys) or a non-accumulator stats payload override this. A keys of None (the default) is a no-op.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)[source]

Replace this accumulator’s statistics from the pooled stats_dict entry (see key_merge).

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()[source]
Return type:

ChowLiuTreeDataEncoder

class ChowLiuTreeAccumulatorFactory(estimators, keys=None, name=None)[source]

Bases: StatisticAccumulatorFactory

Factory for ChowLiuTreeAccumulator.

Parameters:

  • estimators (Sequence[ParameterEstimator])

  • keys (str | None)

  • name (str | None)

make()[source]
Return type:

ChowLiuTreeAccumulator

class ChowLiuTreeEstimator(estimators, root=0, pseudo_count=None, mi_pseudo_count=None, default_policy='marginal', keys=None, name=None)[source]

Bases: ParameterEstimator

Estimate a generic Chow-Liu tree from fixed-length tuple observations.

Structure learning uses empirical mutual information over observed field values, so it is best suited to finite/enumerable or intentionally discretized coordinates. Once an edge is chosen, the child conditional distribution for each parent value is estimated with that child’s supplied estimator.

Parameters:

  • estimators (Sequence[ParameterEstimator | SequenceEncodableProbabilityDistribution])

  • root (int)

  • pseudo_count (float | None)

  • mi_pseudo_count (float | None)

  • default_policy (str)

  • keys (str | None)

  • name (str | None)

accumulator_factory()[source]
Return type:

ChowLiuTreeAccumulatorFactory

estimate(nobs, suff_stat)[source]
Parameters:
Return type:

ChowLiuTreeDistribution

class ChowLiuTreeDataEncoder[source]

Bases: DataSequenceEncoder

Raw tuple encoder for generic Chow-Liu tree observations.

seq_encode(x)[source]

Encode the iid observation sequence x for vectorized evaluation.

Parameters:

x (Sequence[Sequence[Any]])

Return type:

tuple[tuple[Any, …], …]