mixle.stats.latent.semi_supervised_hidden_markov_model module

Semi-supervised hidden Markov model: each observation may carry a per-position state prior.

A SemiSupervisedHiddenMarkovModelDistribution is an HMM with shared emissions and transitions in which every observation can carry soft evidence (a prior) over the hidden state at each position of the sequence – not only the initial state. An observation is a pair (emission_seq, state_prior):

• emission_seq: a length-T sequence of emissions (data type of the emission distributions).

• state_prior: an optional T-by-S array of non-negative weights. Row t is a prior / soft label over the S hidden states at position t; it multiplies the hidden-state distribution there. None (or an all-ones row) imposes no constraint. There is no separate learned initial distribution – the prior at position 0 plays that role (uniform when absent).

The prior folds into the forward-backward as an extra multiplicative factor on the emission likelihood at every position, so it shapes both scoring (log_density) and the EM E-step. Only the transitions and emissions (and an optional length distribution) are learned; the priors are given side information. With every prior None the model is an ordinary HMM with a uniform initial state distribution.

Defines SemiSupervisedHiddenMarkovModelDistribution, SemiSupervisedHiddenMarkovSampler, SemiSupervisedHiddenMarkovEstimatorAccumulator, SemiSupervisedHiddenMarkovEstimatorAccumulatorFactory, SemiSupervisedHiddenMarkovEstimator, and SemiSupervisedHiddenMarkovDataEncoder.

class SemiSupervisedHiddenMarkovSampler(dist, seed=None)

Bases: DistributionSampler

Sample emission sequences from the HMM with a uniform initial state distribution.

Priors are external side information, so sampled observations carry None as their prior.

Parameters:

dist (SemiSupervisedHiddenMarkovModelDistribution)

sample(size=None)

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.

class SemiSupervisedHiddenMarkovEstimatorAccumulator(accumulators, len_accumulator=None, keys=(None, None))

Bases: SequenceEncodableStatisticAccumulator

Baum-Welch sufficient statistics for the semi-supervised HMM (transition + emission counts, length).

update(x, weight, estimate)

initialize(x, weight, rng)

seq_update(x, weights, estimate)

seq_initialize(x, weights, rng)

combine(suff_stat)

value()

from_value(x)

key_merge(stats_dict)

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.

key_replace(stats_dict)

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

acc_to_encoder()

class SemiSupervisedHiddenMarkovEstimatorAccumulatorFactory(factories, len_factory=None, keys=(None, None))

Bases: StatisticAccumulatorFactory

make()

class SemiSupervisedHiddenMarkovEstimator(estimators, len_estimator=None, pseudo_count=None, name=None, keys=(None, None), terminal_states=None)

Bases: ParameterEstimator

accumulator_factory()

estimate(nobs, suff_stat)

class SemiSupervisedHiddenMarkovDataEncoder(emission_encoder, len_encoder=None)

Bases: DataSequenceEncoder

Encode a sequence of (emission_seq, state_prior) observations for the semi-supervised HMM.

seq_encode(x)

Encode the iid observation sequence x for vectorized evaluation.

class SemiSupervisedHiddenMarkovModelDistribution(topics, transitions, len_dist=None, name=None, keys=None, use_numba=False, terminal_states=None)

Bases: SequenceEncodableProbabilityDistribution

HMM with shared emissions/transitions where each observation may carry a per-position state prior.

compute_capabilities()

density(x)

Return the probability density or mass at a single observation.

Concrete default: exponentiate log_density (the abstract method subclasses must provide). Leaves with a cheaper closed form may override this.

Return type:

float

log_density(x)

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

Return type:

float

seq_log_density(x)

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

Return type:

ndarray

density_semantics()

What log_density returns relative to the true log-density (default: exact).

Override to declare that this distribution’s log_density is a variational lower bound (ELBO), an upper bound, or an approximation rather than the exact log p(x). This is surfaced as the ExactDensity capability and noted in mixle.describe(), so code that needs an exact likelihood can require(x, ExactDensity) instead of silently trusting a bound.

sampler(seed=None)

Return a sampler for drawing observations from this distribution.

estimator(pseudo_count=None)

Return an estimator for fitting this distribution from data.

dist_to_encoder()

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

SemiSupervisedHiddenMarkovModelSampler

alias of SemiSupervisedHiddenMarkovSampler

SemiSupervisedHiddenMarkovModelEstimator

alias of SemiSupervisedHiddenMarkovEstimator

SemiSupervisedHiddenMarkovModelDataEncoder

alias of SemiSupervisedHiddenMarkovDataEncoder

SemiSupervisedHiddenMarkovModelAccumulator

alias of SemiSupervisedHiddenMarkovEstimatorAccumulator

SemiSupervisedHiddenMarkovModelAccumulatorFactory

alias of SemiSupervisedHiddenMarkovEstimatorAccumulatorFactory

SemiSupervisedHiddenMarkovAccumulator

alias of SemiSupervisedHiddenMarkovEstimatorAccumulator

SemiSupervisedHiddenMarkovAccumulatorFactory

alias of SemiSupervisedHiddenMarkovEstimatorAccumulatorFactory