mixle.stats.trees.integer_chow_liu_tree module¶

Create, estimate, and sample from an integer Chow Liu Tree distribution.

Defines the IntegerChowLiuTreeDistribution, IntegerChowLiuTreeSampler, IntegerChowLiuTreeAccumulatorFactory, IntegerChowLiuTreeAccumulator, IntegerChowLiuTreeEstimator, and the IntegerChowLiuTreeDataEncoder classes for use with mixle.

mixle supports Chow & Liu trees [1] through the IntegerChowLiuTree (Integer Chow Liu Tree) class of objects. IntegerChowLiuTrees model non-Markov conditional dependence for fixed-length sequences of integers with the likelihood functions of the form

P(x_1, x_2,..,x_n) = P(x_i1) P(x_{i_2}|x_{j_2})*…*P(x_{i_n}|x_{j_n}),

where j_k < i_k for all k = 1,2,3,..N.

Data type: Union[Sequence[int], np.ndarray] .

class IntegerChowLiuTreeDistribution(dependency_list, conditional_log_densities, feature_order=None, name=None)[source]

Bases: SequenceEncodableProbabilityDistribution

Integer Chow-Liu tree distribution factorizing a joint over fixed-length integer vectors along a tree.

Data type: Union[Sequence[int], np.ndarray] (fixed-length vector of non-negative integers).

Parameters:

dependency_list (list[tuple[int, int | None]])
conditional_log_densities (Sequence[float] | ndarray)
feature_order (Sequence[int] | None)
name (str | None)

classmethod compute_capabilities()[source]

classmethod compute_declaration()[source]

density(x)[source]

Density of integer Chow-Liu tree distribution at observation x.

See log_density() for details.

Parameters:: x (Union[Sequence[int], np.ndarray]) – Fixed-length vector of non-negative integers.
Returns:: Density at observation x.
Return type:: float

log_density(x)[source]

Log-density of integer Chow-Liu tree distribution at observation x.

Sums the conditional log-densities of each feature given its parent in the dependency tree (the root feature contributes its marginal log-density).

Parameters:: x (Union[Sequence[int], np.ndarray]) – Fixed-length vector of non-negative integers.
Returns:: Log-density at observation x.
Return type:: float

seq_log_density(x)[source]

Vectorized evaluation of log-density at sequence encoded input x.

Parameters:: x (np.ndarray) – 2-d numpy array of N integer vectors with num_features columns.
Returns:: Numpy array of log-density (float) of length N.
Return type:: ndarray

backend_seq_log_density(x, engine)[source]

Engine-neutral vectorized table lookup for fixed integer tree factors.

Parameters:

x (ndarray)
engine (Any)

Return type:

Any

sampler(seed=None)[source]

Create an IntegerChowLiuTreeSampler object from parameters of IntegerChowLiuTreeDistribution instance.

Parameters:: seed (Optional[int]) – Used to set seed in random sampler.
Returns:: IntegerChowLiuTreeSampler object.
Return type:: IntegerChowLiuTreeSampler

estimator(pseudo_count=None)[source]

Create an IntegerChowLiuTreeEstimator object.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: IntegerChowLiuTreeEstimator object.
Return type:: IntegerChowLiuTreeEstimator

dist_to_encoder()[source]

Returns an IntegerChowLiuTreeDataEncoder object for encoding sequences of data.

Return type:: IntegerChowLiuTreeDataEncoder

enumerator()[source]

Returns IntegerChowLiuTreeEnumerator iterating fixed-length integer vectors in descending probability order.

Return type:: IntegerChowLiuTreeEnumerator

class IntegerChowLiuTreeEnumerator(dist)[source]

Bases: DistributionEnumerator

Enumerates the finite support of an integer Chow-Liu tree.

Parameters:: dist (IntegerChowLiuTreeDistribution)

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

Bases: DistributionSampler

Sampler for the IntegerChowLiuTreeDistribution. Samples each feature given its sampled parent value.

Parameters:

dist (IntegerChowLiuTreeDistribution)
seed (int | None)

sample(size=None)[source]

Draw iid integer vectors from the integer Chow-Liu tree distribution.

Features are drawn in dependency order: the root from its marginal, each remaining feature from its conditional given the sampled parent value.

Parameters:: size (Optional[int]) – Number of samples to draw. If None, a single vector is returned.
Returns:: A single integer vector (List[int]) if size is None, else a list of size vectors.
Return type:: list[int | None] | Sequence[list[int | None]]

class IntegerChowLiuTreeAccumulator(num_features, num_states, keys=None, name=None)[source]

Bases: SequenceEncodableStatisticAccumulator

Accumulator for the IntegerChowLiuTreeDistribution. Tracks pairwise joint and marginal feature-state counts.

Parameters:

num_features (int)
num_states (int)
keys (str | None)
name (str | None)

update(x, weight, estimate)[source]

Update pairwise joint and marginal counts with a weighted observation.

Parameters:

x (Union[Sequence[int], np.ndarray]) – Fixed-length vector of non-negative integers.
weight (float) – Weight for observation.
estimate (Optional[IntegerChowLiuTreeDistribution]) – Previous estimate (unused).

Return type:

None

seq_update(x, weights, estimate)[source]

Vectorized update of pairwise joint and marginal counts from sequence encoded data.

Parameters:

x (np.ndarray) – 2-d numpy array of N integer vectors with num_features columns.
weights (np.ndarray) – Weights for each of the N observations.
estimate (Optional[IntegerChowLiuTreeDistribution]) – Previous estimate (unused).

Return type:

None

initialize(x, weight, rng)[source]

Initialize sufficient statistics with a weighted observation.

Parameters:

x (Union[Sequence[int], np.ndarray]) – Fixed-length vector of non-negative integers.
weight (float) – Weight for observation.
rng (Optional[RandomState]) – Random number generator (unused).

Return type:

None

seq_initialize(x, weights, rng)[source]

Vectorized initialization of sufficient statistics from sequence encoded data.

Parameters:

x (np.ndarray) – 2-d numpy array of N integer vectors with num_features columns.
weights (np.ndarray) – Weights for each of the N observations.
rng (Optional[RandomState]) – Random number generator (unused).

Return type:

None

combine(suff_stat)[source]

Combine sufficient statistics from another accumulator into this one.

Count arrays are expanded if the incoming statistics track more states.

Parameters:: suff_stat (Tuple[int, int, np.ndarray, np.ndarray]) – Tuple of number of features, number of states, pairwise joint counts, and marginal counts.
Returns:: Self, with aggregated sufficient statistics.
Return type:: IntegerChowLiuTreeAccumulator

value()[source]

Returns sufficient statistics as a Tuple of number of features, number of states, pairwise joint counts, and marginal counts.

Return type:: tuple[int, int, ndarray, ndarray]

from_value(x)[source]

Set sufficient statistics of accumulator from value x.

Parameters:: x (Tuple[int, int, np.ndarray, np.ndarray]) – Tuple of number of features, number of states, pairwise joint counts, and marginal counts.
Returns:: Self, with sufficient statistics set to x.
Return type:: IntegerChowLiuTreeAccumulator

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

key_merge(stats_dict)[source]

No-op kept for interface consistency (keyed merging is not supported for IntegerChowLiuTreeAccumulator).

Parameters:: stats_dict (Dict[str, Any]) – Dict mapping keys to shared sufficient statistics (ignored).
Returns:: None.
Return type:: None

key_replace(stats_dict)[source]

No-op kept for interface consistency (keyed merging is not supported for IntegerChowLiuTreeAccumulator).

Parameters:: stats_dict (Dict[str, Any]) – Dict mapping keys to shared sufficient statistics (ignored).
Returns:: None.
Return type:: None

acc_to_encoder()[source]

Returns an IntegerChowLiuTreeDataEncoder object for encoding sequences of data.

Return type:: IntegerChowLiuTreeDataEncoder

class IntegerChowLiuTreeAccumulatorFactory(num_features=None, num_states=None, keys=None, name=None)[source]

Bases: StatisticAccumulatorFactory

Factory for creating IntegerChowLiuTreeAccumulator objects.

Parameters:

num_features (int | None)
num_states (int | None)
keys (str | None)
name (str | None)

make()[source]

Returns a new IntegerChowLiuTreeAccumulator object.

Return type:: IntegerChowLiuTreeAccumulator

class IntegerChowLiuTreeEstimator(num_features=None, num_states=None, pseudo_count=None, suff_stat=None, keys=None, name=None)[source]

Bases: ParameterEstimator

Estimator for the IntegerChowLiuTreeDistribution. Learns the dependency tree with the Chow-Liu algorithm.

Parameters:

num_features (int | None)
num_states (int | None)
pseudo_count (float | None)
suff_stat (Any | None)
keys (str | None)
name (str | None)

accumulator_factory()[source]: Returns an IntegerChowLiuTreeAccumulatorFactory for creating IntegerChowLiuTreeAccumulator objects.

estimate(nobs, suff_stat)[source]

Estimate an IntegerChowLiuTreeDistribution from sufficient statistics via the Chow-Liu algorithm.

Pairwise mutual information is computed from the (optionally smoothed) joint and marginal counts, a maximum mutual information spanning tree is extracted, and conditional densities are computed along the tree rooted at feature 0.

Parameters:

nobs (Optional[float]) – Number of observations (unused).
suff_stat (Tuple[int, int, np.ndarray, np.ndarray]) – Tuple of number of features, number of states, pairwise joint counts, and marginal counts.

Returns:

IntegerChowLiuTreeDistribution object.

class IntegerChowLiuTreeDataEncoder[source]

Bases: DataSequenceEncoder

Data encoder for sequences of fixed-length integer vector observations.

seq_encode(x)[source]

Encode a sequence of N integer vectors for vectorized functions.

Parameters:: x (Union[List[int], np.ndarray]) – Sequence of N fixed-length integer vectors.
Returns:: 2-d numpy array of ints with N rows and num_features columns.
Return type:: ndarray