Categorical HMM¶
The Categorical HMM is a variant of HMM that uses a discrete probability distribution over a finite set of symbols as the emission distribution for each state.
This HMM variant can be used to recognize categorical univariate sequences.
Emissions¶
The emission distribution \(b_m\) of an observation \(o^{(t)}\) at time \(t\) for state \(m\) is given by a probability vector:
Where:
 \(\mathcal{S}=\{s_0,s_1,\ldots,s_K\}\) is a finite set of observation symbols.
 \(o^{(t)}\in\mathcal{S}\) is a single observation at time \(t\).
 \(q^{(t)}\) is a discrete random variable representing the hidden state at time \(t\).
 \(p_{m,k}=\mathbb{P}\big(o^{(t)}=s_k\ \ q^{(t)}=m\big)\) is the probability of observing \(s_k\) while in state \(m\).
The emission distributions for all states can be represented by a single \(M\times K\) emission matrix:
Note
Observation symbols must be encoded as integers. Consider performing label encoding using sklearn.preprocessing.LabelEncoder
.
API reference¶
Class¶
A hidden Markov model with univariate categorical emissions. 
Methods¶

Initializes the 

The Akaike information criterion of the model, evaluated with the maximum likelihood of 

The Bayesian information criterion of the model, evaluated with the maximum likelihood of 

Fit the HMM to the sequences in 

Freeze the trainable parameters of the HMM, preventing them from being updated during the Baum—Welch algorithm. 

Calculate the loglikelihood of the HMM generating a single observation sequence. 

Set the state emission distribution of the HMM's emission model. 

Set the initial state probabilities. 

Set the transition probability matrix. 

Unfreeze the trainable parameters of the HMM, allowing them to be updated during the Baum—Welch algorithm. 
Number of trainable parameters — requires 
 class sequentia.models.hmm.variants.CategoricalHMM¶
A hidden Markov model with univariate categorical emissions.
Examples
Using a
CategoricalHMM
to learn how to recognize DNA sequences from the synthetase gene family.See
load_gene_families()
for more information on the sample dataset used in this example.import numpy as np from sequentia.datasets import load_gene_families from sequentia.models.hmm import CategoricalHMM # Seed for reproducible pseudorandomness random_state = np.random.RandomState(1) # Fetch DNA sequences for the synthetase gene family (no. 4) data, enc = load_gene_families(families=[4]) train_data, test_data = data.split(test_size=0.2, random_state=random_state) # Create and train a CategoricalHMM to recognize the synthetase DNA sequences model = CategoricalHMM(random_state=random_state) model.fit(train_data.X, lengths=train_data.lengths) # Calculate the loglikelihood of the first test sample being generated by this model x, y = test_data[0] model.score(x)
 __init__(*, n_states=5, topology=TopologyMode.LEFT_RIGHT, random_state=None, hmmlearn_kwargs=None)¶
Initializes the
CategoricalHMM
. Parameters:
self (CategoricalHMM) –
n_states (int) – Number of states in the Markov chain.
topology (TopologyMode  None) –
Transition topology of the Markov chain — see Topologies.
If
None
, behaves the same as'ergodic'
but with hmmlearn initialization.random_state (int  RandomState  None) – Seed or
numpy.random.RandomState
object for reproducible pseudorandomness.hmmlearn_kwargs (dict[str, Any]  None) – Additional keyword arguments provided to the hmmlearn HMM constructor.
 Return type:
 aic(X, *, lengths=None)¶
The Akaike information criterion of the model, evaluated with the maximum likelihood of
X
. Parameters:
 Returns:
The Akaike information criterion.
 Return type:
Notes
This method requires a trained model — see
fit()
.
 bic(X, *, lengths=None)¶
The Bayesian information criterion of the model, evaluated with the maximum likelihood of
X
. Parameters:
 Returns:
The Bayesian information criterion.
 Return type:
Notes
This method requires a trained model — see
fit()
.
 fit(X, *, lengths=None)¶
Fit the HMM to the sequences in
X
, using the Baum—Welch algorithm. Parameters:
 Returns:
The fitted HMM.
 Return type:
BaseHMM
 freeze(params=None, /)¶
Freeze the trainable parameters of the HMM, preventing them from being updated during the Baum—Welch algorithm.
 Parameters:
self (CategoricalHMM) –
params (str  None) –
A string specifying which parameters to freeze. Can contain a combination of:
's'
for initial state probabilities,'t'
for transition probabilities,'e'
for emission probailities.
 Return type:
None
Notes
If used, this method should normally be called before
fit()
.See also
unfreeze
Unfreeze the trainable parameters of the HMM, allowing them to be updated during the Baum—Welch algorithm.
 score(x, /)¶
Calculate the loglikelihood of the HMM generating a single observation sequence.
 Parameters:
 Returns:
The loglikelihood.
 Return type:
Notes
This method requires a trained model — see
fit()
.
 set_state_emission_probs(probs, /)¶
Set the state emission distribution of the HMM’s emission model.
If this method is not called, emission probabilities will be initialized by hmmlearn.
 Parameters:
self (CategoricalHMM) –
probs (ndarray[Any, dtype[float64]]) – Array of emission probabilities.
 Return type:
None
Notes
If used, this method should normally be called before
fit()
.
 set_state_start_probs(probs=TransitionMode.RANDOM, /)¶
Set the initial state probabilities.
If this method is not called, initial state probabilities are initialized depending on the value of
topology
provided to__init__()
.If
topology
was set to'ergodic'
,'leftright'
or'linear'
, then random probabilities will be assigned according to the topology by callingset_state_start_probs()
withprobs='random'
.If
topology
was set toNone
, then initial state probabilities will be initialized by hmmlearn.
 Parameters:
self (BaseHMM) –
probs (ndarray[Any, dtype[float64]]  TransitionMode) –
Probabilities or probability type to assign as initial state probabilities.
If an
Array
, should be a vector of starting probabilities for each state.If
'uniform'
, there is an equal probability of starting in any state.If
'random'
, the vector of initial state probabilities is sampled from a Dirichlet distribution with unit concentration parameters.
 Return type:
None
Notes
If used, this method should normally be called before
fit()
.
 set_state_transition_probs(probs=TransitionMode.RANDOM, /)¶
Set the transition probability matrix.
If this method is not called, transition probabilities are initialized depending on the value of
topology
provided to__init__()
:If
topology
was set to'ergodic'
,'leftright'
or'linear'
, then random probabilities will be assigned according to the topology by callingset_state_transition_probs()
withvalue='random'
.If
topology
was set toNone
, then initial state probabilities will be initialized by hmmlearn.
 Parameters:
self (BaseHMM) –
probs (ndarray[Any, dtype[float64]]  TransitionMode) –
Probabilities or probability type to assign as state transition probabilities.
If an
Array
, should be a matrix of probabilities where each row must some to one and represents the probabilities of transitioning out of a state.If
'uniform'
, for each state there is an equal probability of transitioning to any state permitted by the topology.If
'random'
, the vector of transition probabilities for each row is sampled from a Dirichlet distribution with unit concentration parameters, according to the shape of the topology.
 Return type:
None
Notes
If used, this method should normally be called before
fit()
.
 unfreeze(params=None, /)¶
Unfreeze the trainable parameters of the HMM, allowing them to be updated during the Baum—Welch algorithm.
 Parameters:
self (CategoricalHMM) –
params (str  None) –
A string specifying which parameters to unfreeze. Can contain a combination of:
's'
for initial state probabilities,'t'
for transition probabilities,'e'
for emission probailities.
 Return type:
None
See also
freeze
Freeze the trainable parameters of the HMM, preventing them from being updated during the Baum—Welch algorithm.
 hmmlearn_kwargs: dict[str, Any]¶
Additional keyword arguments provided to the hmmlearn HMM constructor.
 random_state: int  RandomState  None¶
Seed or
numpy.random.RandomState
object for reproducible pseudorandomness.
 topology: TopologyMode¶
Transition topology of the Markov chain — see Topologies.