mixle.stats.sequences.markov_transform module

Create, estimate, and sample from a Markov transform model for pairs of count-sets producing a third.

Defines the MarkovTransformDistribution, MarkovTransformSampler, MarkovTransformAccumulatorFactory, MarkovTransformAccumulator, MarkovTransformEstimator, and the MarkovTransformDataEncoder classes for use with mixle.

Data type: Tuple[List[Tuple[int, float]], List[Tuple[int, float]], List[Tuple[int, float]]]: An observation (S1, S2, S3) consists of three bags of integer values in {0,…,W-1}, each given as a list of (value, count) pairs. The members of S1 and S2 are drawn iid from an initial probability vector p, and each member w of S3 is generated by picking a pair (u, v) uniformly from S1 x S2 and drawing w from the conditional distribution P(w | u, v), stored as a sparse (W*W by W) matrix with row index u*W + v. With regularization weight alpha, the log-likelihood is

log(P(S1, S2, S3)) = sum_{u in S1} c_u*log(p_u) + sum_{v in S2} c_v*log(p_v)

• sum_{w in S3} c_w*log( sum_{u,v} ((1-alpha)*P(w|u,v) + alpha/W)*c_u*c_v/(n1*n2) ),

where c_u is the count attached to value u and n1, n2 are the total counts of S1 and S2. An optional length distribution len_dist models the total counts [n1, n2, n3].

class MarkovTransformDistribution(init_prob_vec, cond_prob_mat, alpha=0.0, len_dist=None)

Bases: SequenceEncodableProbabilityDistribution

MarkovTransformDistribution object modeling two count-sets transforming into a third count-set.

density(x)

Density of the Markov transform model at observation x.

See log_density() for details.

Parameters:

x – Observation tuple (S1, S2, S3), each a list of (value, count) pairs.

Returns:

Density at observation x.

log_density(x)

Log-density of the Markov transform model at observation x.

Computes log(P(S1)) + log(P(S2)) + log(P(S3 | S1, S2)), plus the log-density of the total counts [n1, n2, n3] under len_dist when provided. See the module docstring for the likelihood form.

Parameters:

x – Observation tuple (S1, S2, S3), each a list of (value, count) pairs.

Returns:

Log-density at observation x.

seq_log_density(x)

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

Parameters:

x – Encoded sequence (from seq_encode or MarkovTransformDataEncoder.seq_encode).

Returns:

Numpy array of log-densities, one per encoded observation.

compute_capabilities()

Return backend capability metadata for this concrete Markov-transform instance.

backend_seq_log_density(x, engine)

Engine-neutral Markov-transform scoring.

The sparse conditional-probability gather stays on the host (scipy sparse), but the per-observation dense reductions (log-likelihood of the transform plus the two marginal terms) run on the active engine (numpy or torch).

seq_encode(x)

Encode a sequence of observations for vectorized calls (legacy method).

Note: this legacy method encodes the lengths with self.len_dist.seq_encode(); prefer dist_to_encoder().seq_encode(x), which uses the length distribution’s DataSequenceEncoder.

Parameters:

x – Sequence of observation tuples (S1, S2, S3), each a list of (value, count) pairs.

Returns:

Tuple (rv, nn, vv) where rv holds per-observation (values, counts) arrays for S1, S2, S3, nn is the encoded length data (None if len_dist is None), and vv is the array of distinct (u, v, w) triples.

sampler(seed=None)

Create a MarkovTransformSampler object from this instance.

Requires len_dist to be set (it samples the total counts [n1, n2, n3]).

Parameters:

seed (Optional[int]) – Used to set seed in random sampler.

Returns:

MarkovTransformSampler object.

estimator(pseudo_count=None)

Create a MarkovTransformEstimator object from this instance.

Parameters:

pseudo_count (Optional[float]) – Used to inflate sufficient statistics.

Returns:

MarkovTransformEstimator object.

dist_to_encoder()

Returns a MarkovTransformDataEncoder object for encoding sequences of data.

class MarkovTransformSampler(dist, seed=None)

Bases: DistributionSampler

MarkovTransformSampler object for sampling observations from a MarkovTransformDistribution.

Parameters:

• dist (MarkovTransformDistribution)

• seed (int | None)

sample(size=None)

Draw ‘size’ iid observations from the Markov transform model.

Each observation is a tuple (S1, S2, S3) of lists of (value, count) pairs. If size is None a single observation is returned, else a list of ‘size’ observations is returned.

Parameters:

size (Optional[int]) – Number of observations to draw. Treated as a single draw if None.

Returns:

A single observation tuple, or a list of observation tuples when size is not None.

class MarkovTransformAccumulator(num_vals, size_acc=None, keys=(None, None))

Bases: InitTransKeyedAccumulator, SequenceEncodableStatisticAccumulator

MarkovTransformAccumulator object for accumulating sufficient statistics of the Markov transform model.

update(x, weight, estimate)

Update sufficient statistics with a single weighted observation.

Parameters:

• x – Observation tuple (S1, S2, S3), each a list of (value, count) pairs.

• weight (float) – Weight of the observation.

• estimate (MarkovTransformDistribution) – Previous estimate used to assign transition responsibility.

Returns:

None.

initialize(x, weight, rng)

Initialize sufficient statistics with a single weighted observation (no previous estimate).

Parameters:

• x – Observation tuple (S1, S2, S3), each a list of (value, count) pairs.

• weight (float) – Weight of the observation.

• rng (RandomState) – Used to initialize the size accumulator if present.

Returns:

None.

seq_initialize(x, weights, rng)

Initialize sufficient statistics with a sequence of weighted encoded observations.

Applies the same updates as initialize() to each encoded observation.

Parameters:

• x – Encoded sequence (from MarkovTransformDataEncoder.seq_encode).

• weights (np.ndarray) – Weights, one per encoded observation.

• rng (RandomState) – Used to initialize the size accumulator if present.

Returns:

None.

seq_update(x, weights, estimate)

Update sufficient statistics with a sequence of weighted encoded observations.

Parameters:

• x – Encoded sequence (from MarkovTransformDataEncoder.seq_encode).

• weights (np.ndarray) – Weights, one per encoded observation.

• estimate (MarkovTransformDistribution) – Previous estimate used to assign transition responsibility.

Returns:

None.

seq_update_engine(x, weights, estimate, engine)

Engine-aware E-step. The per-observation transition responsibilities are computed on the active engine (numpy or torch); the sparse conditional gather and the sparse count scatter stay on the host, since the sufficient statistic is a sparse matrix. Mirrors seq_update.

combine(suff_stat)

Merge the sufficient statistics of another accumulator into this one.

Parameters:

suff_stat – Tuple (init_count, trans_count, size_value) from another accumulator’s value().

Returns:

This MarkovTransformAccumulator object.

value()

Returns the sufficient statistic tuple (init_count, trans_count, size_value).

from_value(x)

Set the sufficient statistics from a value() tuple.

Parameters:

x – Tuple (init_count, trans_count, size_value).

Returns:

This MarkovTransformAccumulator object.

acc_to_encoder()

Returns a MarkovTransformDataEncoder object for encoding sequences of data.

class MarkovTransformAccumulatorFactory(num_vals, len_factory, keys)

Bases: StatisticAccumulatorFactory

MarkovTransformAccumulatorFactory object for creating MarkovTransformAccumulator objects.

make()

Returns a new MarkovTransformAccumulator object.

class MarkovTransformEstimator(num_vals=MISSING, alpha=0.0, len_estimator=None, suff_stat=None, pseudo_count=None, keys=(None, None), num_values=MISSING)

Bases: ParameterEstimator

MarkovTransformEstimator object for estimating MarkovTransformDistribution objects from statistics.

accumulator_factory()

Returns a MarkovTransformAccumulatorFactory object for this estimator.

accumulatorFactory()

Deprecated alias for accumulator_factory().

estimate(nobs, suff_stat)

Estimate a MarkovTransformDistribution from aggregated sufficient statistics.

Arg suff_stat is a tuple of length 3 containing:

suff_stat[0] (np.ndarray): Weighted counts for the initial probability vector. suff_stat[1] (csc_matrix): Weighted (W*W by W) counts for the conditional probability matrix. suff_stat[2]: Sufficient statistics for the total-count distribution (None if not tracked).

Parameters:

• nobs (Optional[float]) – Weighted number of observations.

• suff_stat – See above for details.

Returns:

MarkovTransformDistribution object.

class MarkovTransformDataEncoder(len_encoder=None)

Bases: DataSequenceEncoder

MarkovTransformDataEncoder object for encoding sequences of Markov transform observations.

seq_encode(x)

Encode a sequence of observations for vectorized calls.

Parameters:

x – Sequence of observation tuples (S1, S2, S3), each a list of (value, count) pairs.

Returns:

Tuple (rv, nn, vv) where rv holds per-observation (values, counts) arrays for S1, S2, S3, nn is the encoded length data (None if len_encoder is None), and vv is the array of distinct (u, v, w) triples.