sequence-models

sequence-models

Use this sub-skill when

Use this sub-skill for pomegranate sequence models: k-th order categorical MarkovChain, dense-transition DenseHMM, sparse-transition SparseHMM, sequence likelihood scoring, sequence sampling, hidden-state posterior decoding, Viterbi paths, variable-length sequence training, and prior-weighted/semi-supervised HMM learning.

Start here

Typical imports:

from pomegranate.distributions import Categorical, ConditionalCategorical, Exponential, Normal
from pomegranate.markov_chain import MarkovChain
from pomegranate.hmm import DenseHMM, SparseHMM

Read references/api-reference.md for constructors, sequence data shapes, dense/sparse edge formats, and examples. Run scripts/smoke_sequence_models.py to verify tiny MarkovChain, DenseHMM, and SparseHMM workflows.

Core workflow

1. Choose the model. Use MarkovChain for observed categorical sequences. Use DenseHMM when hidden state transitions are dense. Use SparseHMM when only a few state transitions are possible.
2. Shape input as sequences. Most HMM/Markov-chain scoring uses (n, length, d). HMM fitting can also accept lists of sequences or grouped tensors for variable lengths.
3. Create emissions. HMM states are pomegranate distributions such as Normal, Exponential, or richer distributions.
4. Define starts, ends, and transitions. Dense HMMs use a transition matrix; sparse HMMs use [start_distribution, end_distribution, probability] edge triples plus optional starts/ends.
5. Train or score. Use fit for Baum-Welch/EM, summarize/from_summaries for chunked updates, and log_probability for sequence likelihoods.
6. Decode states. Use predict, predict_proba, predict_log_proba, or viterbi depending on whether you need posterior marginals or a best path.

Route elsewhere when

• You need base emissions or categorical distributions: read ../distributions/SKILL.md.
• You need non-sequential mixtures or classifiers: read ../mixtures-and-classifiers/SKILL.md.
• You need Bayesian networks or factor graphs over discrete variables: read ../graph-models/SKILL.md.

Guardrails

• HMMs are over sequences; do not pass ordinary (n, d) arrays to HMM scoring/fitting unless the method specifically documents that format.
• SparseHMM needs explicit nonzero edges; if every state connects to every state, use DenseHMM.
• Sampling from HMMs requires either fixed sample_length or usable end probabilities.
• Prior tensors for HMMs must align with sequence shape and state count.
• Read references/troubleshooting.md when variable-length data, edge formats, start/end probabilities, priors, or sampling fail.