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)

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:

• parents (Sequence[int | None])

• marginal_dists (Sequence[SequenceEncodableProbabilityDistribution])

• conditional_dists (Sequence[dict[Hashable, SequenceEncodableProbabilityDistribution] | None])

• default_dists (Sequence[SequenceEncodableProbabilityDistribution | None] | None)

• feature_order (Sequence[int] | None)

• parent_values (Sequence[dict[Hashable, Any]] | None)

• name (str | None)

compute_capabilities()

Describe backend support shared by the tree’s component distributions.

compute_declaration()

Return a composite compute declaration for tree marginals and conditionals.

density(x)

Return the probability density or mass at a single observation.

Parameters:

x (Sequence[Any])

Return type:

float

conditional_dist(child, parent_value)

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

Parameters:

• child (int)

• parent_value (Any)

Return type:

SequenceEncodableProbabilityDistribution | None

log_density(x)

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

Parameters:

x (Sequence[Any])

Return type:

float

seq_log_density(x)

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

Parameters:

x (Sequence[Sequence[Any]])

Return type:

ndarray

backend_seq_log_density(x, engine)

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

Parameters:

• x (Sequence[Sequence[Any]])

• engine (Any)

Return type:

Any

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

Parameters:

seed (int | None)

Return type:

ChowLiuTreeSampler

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

Parameters:

pseudo_count (float | None)

Return type:

ChowLiuTreeEstimator

dist_to_encoder()

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

Return type:

ChowLiuTreeDataEncoder

enumerator()

Return an enumerator over the distribution support when available.

Return type:

ChowLiuTreeEnumerator

class ChowLiuTreeEnumerator(dist)

Bases: DistributionEnumerator

Finite-support enumerator for a ChowLiuTreeDistribution.

Parameters:

dist (ChowLiuTreeDistribution)

class ChowLiuTreeSampler(dist, seed=None)

Bases: DistributionSampler

Sampler for a generic Chow-Liu tree.

Parameters:

• dist (ChowLiuTreeDistribution)

• seed (int | None)

sample(size=None)

Draw one tuple, or size iid tuples, from the tree.

Parameters:

size (int | None)

Return type:

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

class ChowLiuTreeAccumulator(estimators, keys=None, name=None)

Bases: SequenceEncodableStatisticAccumulator

Accumulator for generic Chow-Liu tree sufficient statistics.

Parameters:

• estimators (Sequence[ParameterEstimator])

• keys (str | None)

• name (str | None)

update(x, weight, estimate)

Accumulate marginals, pair counts, and conditional child statistics for one tuple.

Parameters:

• x (Sequence[Any])

• weight (float)

• estimate (ChowLiuTreeDistribution | None)

Return type:

None

initialize(x, weight, rng)

Initialize all marginal and conditional accumulators from one tuple.

Parameters:

• x (Sequence[Any])

• weight (float)

• rng (RandomState)

Return type:

None

seq_update(x, weights, estimate)

Accumulate a batch of tuple observations with corresponding weights.

Parameters:

• x (Sequence[Sequence[Any]])

• weights (ndarray)

• estimate (ChowLiuTreeDistribution | None)

Return type:

None

seq_initialize(x, weights, rng)

Initialize from a batch of tuple observations and weights.

Parameters:

• x (Sequence[Sequence[Any]])

• weights (ndarray)

• rng (RandomState)

Return type:

None

combine(suff_stat)

Merge another Chow-Liu sufficient-statistic value.

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

Return serialized statistics for structure learning and conditional M-steps.

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)

Replace this accumulator from a serialized Chow-Liu statistic value.

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)

Scale all weight-linear statistics by c.

Parameters:

c (float)

Return type:

ChowLiuTreeAccumulator

key_merge(stats_dict)

Merge keyed tree, marginal, and conditional statistics into stats_dict.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

key_replace(stats_dict)

Replace keyed tree, marginal, and conditional statistics when available.

Parameters:

stats_dict (dict[str, Any])

Return type:

None

acc_to_encoder()

Return the tuple encoder compatible with this accumulator.

Return type:

ChowLiuTreeDataEncoder

class ChowLiuTreeAccumulatorFactory(estimators, keys=None, name=None)

Bases: StatisticAccumulatorFactory

Factory for ChowLiuTreeAccumulator.

Parameters:

• estimators (Sequence[ParameterEstimator])

• keys (str | None)

• name (str | None)

make()

Create a fresh Chow-Liu tree accumulator.

Return type:

ChowLiuTreeAccumulator

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

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

Return an accumulator factory for Chow-Liu structure and parameter statistics.

Return type:

ChowLiuTreeAccumulatorFactory

estimate(nobs, suff_stat)

Estimate the Chow-Liu tree structure and all node distributions.

Parameters:

• nobs (float | None)

• 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:

ChowLiuTreeDistribution

class ChowLiuTreeDataEncoder

Bases: DataSequenceEncoder

Raw tuple encoder for generic Chow-Liu tree observations.

seq_encode(x)

Encode observations as immutable feature tuples.

Parameters:

x (Sequence[Sequence[Any]])

Return type:

tuple[tuple[Any, …], …]