hmm.hpp
Go to the documentation of this file.
1 
14 #ifndef MLPACK_METHODS_HMM_HMM_HPP
15 #define MLPACK_METHODS_HMM_HMM_HPP
16 
17 #include <mlpack/prereqs.hpp>
19 
20 namespace mlpack {
21 namespace hmm {
22 
84 template<typename Distribution = distribution::DiscreteDistribution>
85 class HMM
86 {
87  public:
105  HMM(const size_t states = 0,
106  const Distribution emissions = Distribution(),
107  const double tolerance = 1e-5);
108 
136  HMM(const arma::vec& initial,
137  const arma::mat& transition,
138  const std::vector<Distribution>& emission,
139  const double tolerance = 1e-5);
140 
169  double Train(const std::vector<arma::mat>& dataSeq);
170 
191  void Train(const std::vector<arma::mat>& dataSeq,
192  const std::vector<arma::Row<size_t> >& stateSeq);
193 
212  double LogEstimate(const arma::mat& dataSeq,
213  arma::mat& stateLogProb,
214  arma::mat& forwardLogProb,
215  arma::mat& backwardLogProb,
216  arma::vec& logScales) const;
217 
236  double Estimate(const arma::mat& dataSeq,
237  arma::mat& stateProb,
238  arma::mat& forwardProb,
239  arma::mat& backwardProb,
240  arma::vec& scales) const;
241 
253  double Estimate(const arma::mat& dataSeq,
254  arma::mat& stateProb) const;
255 
267  void Generate(const size_t length,
268  arma::mat& dataSequence,
269  arma::Row<size_t>& stateSequence,
270  const size_t startState = 0) const;
271 
282  double Predict(const arma::mat& dataSeq,
283  arma::Row<size_t>& stateSeq) const;
284 
291  double LogLikelihood(const arma::mat& dataSeq) const;
292 
307  double EmissionLogScaleFactor(const arma::vec& emissionLogProb,
308  arma::vec& forwardLogProb) const;
309 
326  double EmissionLogLikelihood(const arma::vec& emissionLogProb,
327  double &logLikelihood,
328  arma::vec& forwardLogProb) const;
329 
345  double LogScaleFactor(const arma::vec &data,
346  arma::vec& forwardLogProb) const;
347 
363  double LogLikelihood(const arma::vec &data,
364  double &logLikelihood,
365  arma::vec& forwardLogProb) const;
378  void Filter(const arma::mat& dataSeq,
379  arma::mat& filterSeq,
380  size_t ahead = 0) const;
381 
393  void Smooth(const arma::mat& dataSeq,
394  arma::mat& smoothSeq) const;
395 
397  const arma::vec& Initial() const { return initialProxy; }
399  arma::vec& Initial()
400  {
401  recalculateInitial = true;
402  return initialProxy;
403  }
404 
406  const arma::mat& Transition() const { return transitionProxy; }
408  arma::mat& Transition()
409  {
410  recalculateTransition = true;
411  return transitionProxy;
412  }
413 
415  const std::vector<Distribution>& Emission() const { return emission; }
417  std::vector<Distribution>& Emission() { return emission; }
418 
420  size_t Dimensionality() const { return dimensionality; }
422  size_t& Dimensionality() { return dimensionality; }
423 
425  double Tolerance() const { return tolerance; }
427  double& Tolerance() { return tolerance; }
428 
432  template<typename Archive>
433  void load(Archive& ar, const uint32_t version);
434 
438  template<typename Archive>
439  void save(Archive& ar, const uint32_t version) const;
440 
441  protected:
449  arma::vec ForwardAtT0(
450  const arma::vec& emissionLogProb,
451  double& logScales) const;
452 
461  arma::vec ForwardAtTn(
462  const arma::vec& emissionLogProb,
463  double& logScales,
464  const arma::vec& prevForwardLogProb) const;
465 
466  // Helper functions.
477  void Forward(const arma::mat& dataSeq,
478  arma::vec& logScales,
479  arma::mat& forwardLogProb) const;
480 
492  void Backward(const arma::mat& dataSeq,
493  const arma::vec& logScales,
494  arma::mat& backwardLogProb) const;
495 
497  std::vector<Distribution> emission;
498 
503  arma::mat transitionProxy;
504 
506  mutable arma::mat logTransition;
507 
508  private:
514  void ConvertToLogSpace() const;
515 
520  arma::vec initialProxy;
521 
523  mutable arma::vec logInitial;
524 
526  size_t dimensionality;
527 
529  double tolerance;
530 
535  mutable bool recalculateInitial;
536 
541  mutable bool recalculateTransition;
542 };
543 
544 } // namespace hmm
545 } // namespace mlpack
546 
547 // Include implementation.
548 #include "hmm_impl.hpp"
549 
550 #endif
void Filter(const arma::mat &dataSeq, arma::mat &filterSeq, size_t ahead=0) const
HMM filtering.
arma::mat transitionProxy
A proxy variable in linear space for logTransition.
Definition: hmm.hpp:503
const arma::vec & Initial() const
Return the vector of initial state probabilities.
Definition: hmm.hpp:397
std::vector< Distribution > emission
Set of emission probability distributions; one for each state.
Definition: hmm.hpp:497
arma::vec & Initial()
Modify the vector of initial state probabilities.
Definition: hmm.hpp:399
arma::vec ForwardAtTn(const arma::vec &emissionLogProb, double &logScales, const arma::vec &prevForwardLogProb) const
Given emission probabilities, computes forward probabilities for time t>0.
const std::vector< Distribution > & Emission() const
Return the emission distributions.
Definition: hmm.hpp:415
Linear algebra utility functions, generally performed on matrices or vectors.
void save(Archive &ar, const uint32_t version) const
Save the object.
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.
double LogScaleFactor(const arma::vec &data, arma::vec &forwardLogProb) const
Compute the log of the scaling factor of the given data at time t.
The core includes that mlpack expects; standard C++ includes and Armadillo.
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.
size_t & Dimensionality()
Set the dimensionality of observations.
Definition: hmm.hpp:422
void Forward(const arma::mat &dataSeq, arma::vec &logScales, arma::mat &forwardLogProb) const
The Forward algorithm (part of the Forward-Backward algorithm).
double Tolerance() const
Get the tolerance of the Baum-Welch algorithm.
Definition: hmm.hpp:425
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 distribut...
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...
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...
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 algori...
arma::vec ForwardAtT0(const arma::vec &emissionLogProb, double &logScales) const
Given emission probabilities, computes forward probabilities at time t=0.
arma::mat & Transition()
Return a modifiable transition matrix reference.
Definition: hmm.hpp:408
arma::mat logTransition
Transition probability matrix. No need to be mutable in mlpack 4.0.
Definition: hmm.hpp:506
double LogLikelihood(const arma::mat &dataSeq) const
Compute the log-likelihood of the given data sequence.
size_t Dimensionality() const
Get the dimensionality of observations.
Definition: hmm.hpp:420
double & Tolerance()
Modify the tolerance of the Baum-Welch algorithm.
Definition: hmm.hpp:427
const arma::mat & Transition() const
Return the transition matrix.
Definition: hmm.hpp:406
void Backward(const arma::mat &dataSeq, const arma::vec &logScales, arma::mat &backwardLogProb) const
The Backward algorithm (part of the Forward-Backward algorithm).
void load(Archive &ar, const uint32_t version)
Load the object.
A class that represents a Hidden Markov Model with an arbitrary type of emission distribution.
Definition: hmm.hpp:85
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 logL...
void Smooth(const arma::mat &dataSeq, arma::mat &smoothSeq) const
HMM smoothing.
double Train(const std::vector< arma::mat > &dataSeq)
Train the model using the Baum-Welch algorithm, with only the given unlabeled observations.
std::vector< Distribution > & Emission()
Return a modifiable emission probability matrix reference.
Definition: hmm.hpp:417