mixle.stats.trees.integer_chow_liu_tree module¶

Integer Chow-Liu tree distributions for fixed-length integer vectors.

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]: Declare backend support for integer Chow-Liu generated kernels.

classmethod compute_declaration()[source]: Return the generated-compute declaration for the integer Chow-Liu tree.

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 a sampler for this integer Chow-Liu tree distribution.

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

estimator(pseudo_count=None)[source]

Create an estimator initialized from this integer Chow-Liu tree distribution.

Parameters:: pseudo_count (Optional[float]) – Used to inflate sufficient statistics.
Returns:: Estimator configured with the same feature count and state count.
Return type:: IntegerChowLiuTreeEstimator

dist_to_encoder()[source]

Return a data encoder for integer Chow-Liu tree observations.

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 all accumulated Chow-Liu sufficient statistics in place.

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]

Return a data encoder for accumulated integer Chow-Liu tree observations.

Return type:: IntegerChowLiuTreeDataEncoder

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

Bases: StatisticAccumulatorFactory

Factory for integer Chow-Liu tree accumulators.

Parameters:

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

make()[source]

Return a new integer Chow-Liu tree accumulator.

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]: Return an accumulator factory configured from this estimator.

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