mlpack
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
mlpack::hmm::HMM< Distribution > Class Template Reference

A class that represents a Hidden Markov Model with an arbitrary type of emission distribution. More...

#include <hmm.hpp>

Public Member Functions

 HMM (const size_t states=0, const Distribution emissions=Distribution(), const double tolerance=1e-5)
 Create the Hidden Markov Model with the given number of hidden states and the given default distribution for emissions. More...
 
 HMM (const arma::vec &initial, const arma::mat &transition, const std::vector< Distribution > &emission, const double tolerance=1e-5)
 Create the Hidden Markov Model with the given initial probability vector, the given transition matrix, and the given emission distributions. More...
 
double Train (const std::vector< arma::mat > &dataSeq)
 Train the model using the Baum-Welch algorithm, with only the given unlabeled observations. More...
 
void Train (const std::vector< arma::mat > &dataSeq, const std::vector< arma::Row< size_t > > &stateSeq)
 Train the model using the given labeled observations; the transition and emission matrices are directly estimated. More...
 
double LogEstimate (const arma::mat &dataSeq, arma::mat &stateLogProb, arma::mat &forwardLogProb, arma::mat &backwardLogProb, arma::vec &logScales) const
 Estimate the probabilities of each hidden state at each time step for each given data observation, using the Forward-Backward algorithm. More...
 
double Estimate (const arma::mat &dataSeq, arma::mat &stateProb, arma::mat &forwardProb, arma::mat &backwardProb, arma::vec &scales) const
 Estimate the probabilities of each hidden state at each time step for each given data observation, using the Forward-Backward algorithm. More...
 
double Estimate (const arma::mat &dataSeq, arma::mat &stateProb) const
 Estimate the probabilities of each hidden state at each time step of each given data observation, using the Forward-Backward algorithm. More...
 
void Generate (const size_t length, arma::mat &dataSequence, arma::Row< size_t > &stateSequence, const size_t startState=0) const
 Generate a random data sequence of the given length. More...
 
double Predict (const arma::mat &dataSeq, arma::Row< size_t > &stateSeq) const
 Compute the most probable hidden state sequence for the given data sequence, using the Viterbi algorithm, returning the log-likelihood of the most likely state sequence. More...
 
double LogLikelihood (const arma::mat &dataSeq) const
 Compute the log-likelihood of the given data sequence. More...
 
double EmissionLogScaleFactor (const arma::vec &emissionLogProb, arma::vec &forwardLogProb) const
 Compute the log of the scaling factor of the given emission probability at time t. More...
 
double EmissionLogLikelihood (const arma::vec &emissionLogProb, double &logLikelihood, arma::vec &forwardLogProb) const
 Compute the log-likelihood of the given emission probability up to time t, storing the result in logLikelihood. More...
 
double LogScaleFactor (const arma::vec &data, arma::vec &forwardLogProb) const
 Compute the log of the scaling factor of the given data at time t. More...
 
double LogLikelihood (const arma::vec &data, double &logLikelihood, arma::vec &forwardLogProb) const
 Compute the log-likelihood of the given data up to time t, storing the result in logLikelihood. More...
 
void Filter (const arma::mat &dataSeq, arma::mat &filterSeq, size_t ahead=0) const
 HMM filtering. More...
 
void Smooth (const arma::mat &dataSeq, arma::mat &smoothSeq) const
 HMM smoothing. More...
 
const arma::vec & Initial () const
 Return the vector of initial state probabilities.
 
arma::vec & Initial ()
 Modify the vector of initial state probabilities.
 
const arma::mat & Transition () const
 Return the transition matrix.
 
arma::mat & Transition ()
 Return a modifiable transition matrix reference.
 
const std::vector< Distribution > & Emission () const
 Return the emission distributions.
 
std::vector< Distribution > & Emission ()
 Return a modifiable emission probability matrix reference.
 
size_t Dimensionality () const
 Get the dimensionality of observations.
 
size_t & Dimensionality ()
 Set the dimensionality of observations.
 
double Tolerance () const
 Get the tolerance of the Baum-Welch algorithm.
 
double & Tolerance ()
 Modify the tolerance of the Baum-Welch algorithm.
 
template<typename Archive >
void load (Archive &ar, const uint32_t version)
 Load the object. More...
 
template<typename Archive >
void save (Archive &ar, const uint32_t version) const
 Save the object. More...
 

Protected Member Functions

arma::vec ForwardAtT0 (const arma::vec &emissionLogProb, double &logScales) const
 Given emission probabilities, computes forward probabilities at time t=0. More...
 
arma::vec ForwardAtTn (const arma::vec &emissionLogProb, double &logScales, const arma::vec &prevForwardLogProb) const
 Given emission probabilities, computes forward probabilities for time t>0. More...
 
void Forward (const arma::mat &dataSeq, arma::vec &logScales, arma::mat &forwardLogProb, arma::mat &logProbs) const
 The Forward algorithm (part of the Forward-Backward algorithm). More...
 
void Backward (const arma::mat &dataSeq, const arma::vec &logScales, arma::mat &backwardLogProb, arma::mat &logProbs) const
 The Backward algorithm (part of the Forward-Backward algorithm). More...
 

Protected Attributes

std::vector< Distribution > emission
 Set of emission probability distributions; one for each state.
 
arma::mat transitionProxy
 A proxy variable in linear space for logTransition. More...
 
arma::mat logTransition
 Transition probability matrix. No need to be mutable in mlpack 4.0.
 

Detailed Description

template<typename Distribution = distribution::DiscreteDistribution>
class mlpack::hmm::HMM< Distribution >

A class that represents a Hidden Markov Model with an arbitrary type of emission distribution.

This HMM class supports training (supervised and unsupervised), prediction of state sequences via the Viterbi algorithm, estimation of state probabilities, generation of random sequences, and calculation of the log-likelihood of a given sequence.

The template parameter, Distribution, specifies the distribution which the emissions follow. The class should implement the following functions:

class Distribution
{
public:
// The type of observation used by this distribution.
typedef something DataType;
// Return the probability of the given observation.
double Probability(const DataType& observation) const;
// Estimate the distribution based on the given observations.
double Train(const std::vector<DataType>& observations);
// Estimate the distribution based on the given observations, given also
// the probability of each observation coming from this distribution.
double Train(const std::vector<DataType>& observations,
const std::vector<double>& probabilities);
};

See the mlpack::distribution::DiscreteDistribution class for an example. One would use the DiscreteDistribution class when the observations are non-negative integers. Other distributions could be Gaussians, a mixture of Gaussians (GMM), or any other probability distribution implementing the four Distribution functions.

Usage of the HMM class generally involves either training an HMM or loading an already-known HMM and taking probability measurements of sequences. Example code for supervised training of a Gaussian HMM (that is, where the emission output distribution is a single Gaussian for each hidden state) is given below.

extern arma::mat observations; // Each column is an observation.
extern arma::Row<size_t> states; // Hidden states for each observation.
// Create an untrained HMM with 5 hidden states and default (N(0, 1))
// Gaussian distributions with the dimensionality of the dataset.
HMM<GaussianDistribution> hmm(5, GaussianDistribution(observations.n_rows));
// Train the HMM (the labels could be omitted to perform unsupervised
// training).
hmm.Train(observations, states);

Once initialized, the HMM can evaluate the probability of a certain sequence (with LogLikelihood()), predict the most likely sequence of hidden states (with Predict()), generate a sequence (with Generate()), or estimate the probabilities of each state for a sequence of observations (with Train()).

Template Parameters
DistributionType of emission distribution for this HMM.

Constructor & Destructor Documentation

◆ HMM() [1/2]

template<typename Distribution>
mlpack::hmm::HMM< Distribution >::HMM ( const size_t  states = 0,
const Distribution  emissions = Distribution(),
const double  tolerance = 1e-5 
)

Create the Hidden Markov Model with the given number of hidden states and the given default distribution for emissions.

Create the Hidden Markov Model with the given number of hidden states and the given number of emission states.

The dimensionality of the observations is taken from the emissions variable, so it is important that the given default emission distribution is set with the correct dimensionality. Alternately, set the dimensionality with Dimensionality(). Optionally, the tolerance for convergence of the Baum-Welch algorithm can be set.

By default, the transition matrix and initial probability vector are set to contain equal probability for each state.

Parameters
statesNumber of states.
emissionsDefault distribution for emissions.
toleranceTolerance for convergence of training algorithm (Baum-Welch).

◆ HMM() [2/2]

template<typename Distribution>
mlpack::hmm::HMM< Distribution >::HMM ( const arma::vec &  initial,
const arma::mat &  transition,
const std::vector< Distribution > &  emission,
const double  tolerance = 1e-5 
)

Create the Hidden Markov Model with the given initial probability vector, the given transition matrix, and the given emission distributions.

Create the Hidden Markov Model with the given transition matrix and the given emission probability matrix.

The dimensionality of the observations of the HMM are taken from the given emission distributions. Alternately, the dimensionality can be set with Dimensionality().

The initial state probability vector should have length equal to the number of states, and each entry represents the probability of being in the given state at time T = 0 (the beginning of a sequence).

The transition matrix should be such that T(i, j) is the probability of transition to state i from state j. The columns of the matrix should sum to 1.

The emission matrix should be such that E(i, j) is the probability of emission i while in state j. The columns of the matrix should sum to 1.

Optionally, the tolerance for convergence of the Baum-Welch algorithm can be set.

Parameters
initialInitial state probabilities.
transitionTransition matrix.
emissionEmission distributions.
toleranceTolerance for convergence of training algorithm (Baum-Welch).

Member Function Documentation

◆ Backward()

template<typename Distribution >
void mlpack::hmm::HMM< Distribution >::Backward ( const arma::mat &  dataSeq,
const arma::vec &  logScales,
arma::mat &  backwardLogProb,
arma::mat &  logProbs 
) const
protected

The Backward algorithm (part of the Forward-Backward algorithm).

Computes backward probabilities for each state for each observation in the given data sequence, using the scaling factors found (presumably) by Forward(). The returned matrix has rows equal to the number of hidden states and columns equal to the number of observations.

Parameters
dataSeqData sequence to compute probabilities for.
logScalesVector of log of scaling factors.
backwardLogProbMatrix in which backward probabilities will be saved.

◆ EmissionLogLikelihood()

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::EmissionLogLikelihood ( const arma::vec &  emissionLogProb,
double &  logLikelihood,
arma::vec &  forwardLogProb 
) const

Compute the log-likelihood of the given emission probability up to time t, storing the result in logLikelihood.

Compute the log-likelihood of the given emission probability up to time t.

This is meant for incremental or streaming computation of the log-likelihood of a sequence. For the first data point, provide an empty forwardLogProb vector.

Parameters
emissionLogProbemission probability at time t.
logLikelihoodLog-likelihood of the given sequence of emission probability up to time t-1. This will be overwritten with the log-likelihood of the given emission probability up to time t.
forwardLogProbVector in which forward probabilities will be saved. Passing forwardLogProb as an empty vector indicates the start of the sequence (i.e. time t=0).
Returns
Log-likelihood of the given sequence of emission up to time t.

◆ EmissionLogScaleFactor()

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::EmissionLogScaleFactor ( const arma::vec &  emissionLogProb,
arma::vec &  forwardLogProb 
) const

Compute the log of the scaling factor of the given emission probability at time t.

To calculate the log-likelihood for the whole sequence, accumulate log scale over the entire sequence This is meant for incremental or streaming computation of the log-likelihood of a sequence. For the first data point, provide an empty forwardLogProb vector.

Parameters
emissionLogProbemission probability at time t.
forwardLogProbVector in which forward probabilities will be saved. Passing forwardLogProb as an empty vector indicates the start of the sequence (i.e. time t=0).
Returns
Log scale factor of the given sequence of emission at time t.

To calculate the log-likelihood for the whole sequence, accumulate log scale over the entire sequence

◆ Estimate() [1/2]

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::Estimate ( const arma::mat &  dataSeq,
arma::mat &  stateProb,
arma::mat &  forwardProb,
arma::mat &  backwardProb,
arma::vec &  scales 
) const

Estimate the probabilities of each hidden state at each time step for each given data observation, using the Forward-Backward algorithm.

Estimate the probabilities of each hidden state at each time step for each given data observation.

Each matrix which is returned has columns equal to the number of data observations, and rows equal to the number of hidden states in the model. The log-likelihood of the most probable sequence is returned.

Parameters
dataSeqSequence of observations.
stateProbMatrix in which the probabilities of each state at each time interval will be stored.
forwardProbMatrix in which the forward probabilities of each state at each time interval will be stored.
backwardProbMatrix in which the backward probabilities of each state at each time interval will be stored.
scalesVector in which the scaling factors at each time interval will be stored.
Returns
Log-likelihood of most likely state sequence.

◆ Estimate() [2/2]

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::Estimate ( const arma::mat &  dataSeq,
arma::mat &  stateProb 
) const

Estimate the probabilities of each hidden state at each time step of each given data observation, using the Forward-Backward algorithm.

Estimate the probabilities of each hidden state at each time step for each given data observation.

The returned matrix of state probabilities has columns equal to the number of data observations, and rows equal to the number of hidden states in the model. The log-likelihood of the most probable sequence is returned.

Parameters
dataSeqSequence of observations.
stateProbProbabilities of each state at each time interval.
Returns
Log-likelihood of most likely state sequence.

◆ Filter()

template<typename Distribution >
void mlpack::hmm::HMM< Distribution >::Filter ( const arma::mat &  dataSeq,
arma::mat &  filterSeq,
size_t  ahead = 0 
) const

HMM filtering.

Computes the k-step-ahead expected emission at each time conditioned only on prior observations. That is E{ Y[t+k] | Y[0], ..., Y[t] }. The returned matrix has columns equal to the number of observations. Note that the expectation may not be meaningful for discrete emissions.

Parameters
dataSeqSequence of observations.
filterSeqVector in which the expected emission sequence will be stored.
aheadNumber of steps ahead (k) for expectations.

◆ Forward()

template<typename Distribution >
void mlpack::hmm::HMM< Distribution >::Forward ( const arma::mat &  dataSeq,
arma::vec &  logScales,
arma::mat &  forwardLogProb,
arma::mat &  logProbs 
) const
protected

The Forward algorithm (part of the Forward-Backward algorithm).

The Forward procedure (part of the Forward-Backward algorithm).

Computes forward probabilities for each state for each observation in the given data sequence. The returned matrix has rows equal to the number of hidden states and columns equal to the number of observations.

Parameters
dataSeqData sequence to compute probabilities for.
logScalesVector in which the log of scaling factors will be saved.
forwardLogProbMatrix in which forward probabilities will be saved.

◆ ForwardAtT0()

template<typename Distribution >
arma::vec mlpack::hmm::HMM< Distribution >::ForwardAtT0 ( const arma::vec &  emissionLogProb,
double &  logScales 
) const
protected

Given emission probabilities, computes forward probabilities at time t=0.

The Forward procedure (part of the Forward-Backward algorithm).

Parameters
emissionLogProbEmission probability at time t=0.
logScalesVector in which the log of scaling factors will be saved.
Returns
Forward probabilities

◆ ForwardAtTn()

template<typename Distribution >
arma::vec mlpack::hmm::HMM< Distribution >::ForwardAtTn ( const arma::vec &  emissionLogProb,
double &  logScales,
const arma::vec &  prevForwardLogProb 
) const
protected

Given emission probabilities, computes forward probabilities for time t>0.

The Forward procedure (part of the Forward-Backward algorithm).

Parameters
emissionLogProbEmission probability at time t>0.
logScalesVector in which the log of scaling factors will be saved.
prevForwardLogProbPrevious forward probabilities.
Returns
Forward probabilities

◆ Generate()

template<typename Distribution >
void mlpack::hmm::HMM< Distribution >::Generate ( const size_t  length,
arma::mat &  dataSequence,
arma::Row< size_t > &  stateSequence,
const size_t  startState = 0 
) const

Generate a random data sequence of the given length.

Generate a random data sequence of a given length.

The data sequence is stored in the dataSequence parameter, and the state sequence is stored in the stateSequence parameter. Each column of dataSequence represents a random observation.

Parameters
lengthLength of random sequence to generate.
dataSequenceVector to store data in.
stateSequenceVector to store states in.
startStateHidden state to start sequence in (default 0).

The data sequence is stored in the dataSequence parameter, and the state sequence is stored in the stateSequence parameter.

◆ load()

template<typename Distribution >
template<typename Archive >
void mlpack::hmm::HMM< Distribution >::load ( Archive &  ar,
const uint32_t  version 
)

Load the object.

Serialize the HMM.

◆ LogEstimate()

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::LogEstimate ( const arma::mat &  dataSeq,
arma::mat &  stateLogProb,
arma::mat &  forwardLogProb,
arma::mat &  backwardLogProb,
arma::vec &  logScales 
) const

Estimate the probabilities of each hidden state at each time step for each given data observation, using the Forward-Backward algorithm.

Estimate the probabilities of each hidden state at each time step for each given data observation.

Each matrix which is returned has columns equal to the number of data observations, and rows equal to the number of hidden states in the model. The log-likelihood of the most probable sequence is returned.

Parameters
dataSeqSequence of observations.
stateLogProbMatrix in which the log probabilities of each state at each time interval will be stored.
forwardLogProbMatrix in which the forward log probabilities of each state at each time interval will be stored.
backwardLogProbMatrix in which the backward log probabilities of each state at each time interval will be stored.
logScalesVector in which the log of scaling factors at each time interval will be stored.
Returns
Log-likelihood of most likely state sequence.

◆ LogLikelihood() [1/2]

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::LogLikelihood ( const arma::mat &  dataSeq) const

Compute the log-likelihood of the given data sequence.

Parameters
dataSeqData sequence to evaluate the likelihood of.
Returns
Log-likelihood of the given sequence.

◆ LogLikelihood() [2/2]

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::LogLikelihood ( const arma::vec &  data,
double &  logLikelihood,
arma::vec &  forwardLogProb 
) const

Compute the log-likelihood of the given data up to time t, storing the result in logLikelihood.

Compute the log-likelihood of the given data up to time t.

This is meant for incremental or streaming computation of the log-likelihood of a sequence. For the first data point, provide an empty forwardLogProb vector.

Parameters
dataobservation at time t.
logLikelihoodLog-likelihood of the given sequence of data up to time t-1.
forwardLogProbVector in which forward probabilities will be saved. Passing forwardLogProb as an empty vector indicates the start of the sequence (i.e. time t=0).
Returns
Log-likelihood of the given sequence of data up to time t.

◆ LogScaleFactor()

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::LogScaleFactor ( const arma::vec &  data,
arma::vec &  forwardLogProb 
) const

Compute the log of the scaling factor of the given data at time t.

To calculate the log-likelihood for the whole sequence, accumulate the log scale factor (the return value of this function) over the entire sequence. This is meant for incremental or streaming computation of the log-likelihood of a sequence. For the first data point, provide an empty forwardLogProb vector.

Parameters
dataobservation at time t.
forwardLogProbVector in which forward probabilities will be saved. Passing forwardLogProb as an empty vector indicates the start of the sequence (i.e. time t=0).
Returns
Log scale factor of the given sequence of data up at time t.

To calculate the log-likelihood for the whole sequence, accumulate log scale over the entire sequence

◆ Predict()

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::Predict ( const arma::mat &  dataSeq,
arma::Row< size_t > &  stateSeq 
) const

Compute the most probable hidden state sequence for the given data sequence, using the Viterbi algorithm, returning the log-likelihood of the most likely state sequence.

Compute the most probable hidden state sequence for the given observation using the Viterbi algorithm.

Parameters
dataSeqSequence of observations.
stateSeqVector in which the most probable state sequence will be stored.
Returns
Log-likelihood of most probable state sequence.

Returns the log-likelihood of the most likely sequence.

◆ save()

template<typename Distribution >
template<typename Archive >
void mlpack::hmm::HMM< Distribution >::save ( Archive &  ar,
const uint32_t  version 
) const

Save the object.

Serialize the HMM.

◆ Smooth()

template<typename Distribution >
void mlpack::hmm::HMM< Distribution >::Smooth ( const arma::mat &  dataSeq,
arma::mat &  smoothSeq 
) const

HMM smoothing.

Computes expected emission at each time conditioned on all observations. That is E{ Y[t] | Y[0], ..., Y[T] }. The returned matrix has columns equal to the number of observations. Note that the expectation may not be meaningful for discrete emissions.

Parameters
dataSeqSequence of observations.
smoothSeqVector in which the expected emission sequence will be stored.

◆ Train() [1/2]

template<typename Distribution >
double mlpack::hmm::HMM< Distribution >::Train ( const std::vector< arma::mat > &  dataSeq)

Train the model using the Baum-Welch algorithm, with only the given unlabeled observations.

Instead of giving a guess transition and emission matrix here, do that in the constructor. Each matrix in the vector of data sequences holds an individual data sequence; each point in each individual data sequence should be a column in the matrix. The number of rows in each matrix should be equal to the dimensionality of the HMM (which is set in the constructor).

It is preferable to use the other overload of Train(), with labeled data. That will produce much better results. However, if labeled data is unavailable, this will work. In addition, it is possible to use Train() with labeled data first, and then continue to train the model using this overload of Train() with unlabeled data.

The tolerance of the Baum-Welch algorithm can be set either in the constructor or with the Tolerance() method. When the change in log-likelihood of the model between iterations is less than the tolerance, the Baum-Welch algorithm terminates.

Note
Train() can be called multiple times with different sequences; each time it is called, it uses the current parameters of the HMM as a starting point for training.
Parameters
dataSeqVector of observation sequences.
Returns
Log-likelihood of state sequence.

Each matrix in the vector of data sequences holds an individual data sequence; each point in each individual data sequence should be a column in the matrix. The number of rows in each matrix should be equal to the dimensionality of the HMM.

It is preferable to use the other overload of Train(), with labeled data. That will produce much better results. However, if labeled data is unavailable, this will work. In addition, it is possible to use Train() with labeled data first, and then continue to train the model using this overload of Train() with unlabeled data.

Parameters
dataSeqSet of data sequences to train on.

◆ Train() [2/2]

template<typename Distribution >
void mlpack::hmm::HMM< Distribution >::Train ( const std::vector< arma::mat > &  dataSeq,
const std::vector< arma::Row< size_t > > &  stateSeq 
)

Train the model using the given labeled observations; the transition and emission matrices are directly estimated.

Each matrix in the vector of data sequences corresponds to a vector in the vector of state sequences. Each point in each individual data sequence should be a column in the matrix, and its state should be the corresponding element in the state sequence vector. For instance, dataSeq[0].col(3) corresponds to the fourth observation in the first data sequence, and its state is stateSeq[0][3]. The number of rows in each matrix should be equal to the dimensionality of the HMM (which is set in the constructor).

Note
Train() can be called multiple times with different sequences; each time it is called, it uses the current parameters of the HMM as a starting point for training.
Parameters
dataSeqVector of observation sequences.
stateSeqVector of state sequences, corresponding to each observation.

Member Data Documentation

◆ transitionProxy

template<typename Distribution = distribution::DiscreteDistribution>
arma::mat mlpack::hmm::HMM< Distribution >::transitionProxy
protected

A proxy variable in linear space for logTransition.

Should be removed in mlpack 4.0.


The documentation for this class was generated from the following files: