README

This package contains a set of functions for evaluating HMMs and GMMs.

The portions written by me are distributed under the terms of the GNU
General Public License.  See the file COPYING for details.

* Functions

 - The important ones:
   - train_gmm  - train a GMM from data
   - eval_gmm   - compute the posterior probability of a GMM given data
   - eval_hmm   - compute the posterior probabilities of all possible HMM
                  state sequences given data
   - decode_hmm - find the most likely state sequence through the HMM
                  given data

 - Utility functions:
   - logsum           - takes the sum of a matrix of log likelihoods
   - lmvnpdf          - compute the log probability of data under a
                        multivariate Gaussian distribution
 
* Data Structures

The functions in this toolbox pass around the following structures:
Note: all probabilities are stored as log probabilities

** GMM
  - gmm.nmix   - number of components in the mixture
  - gmm.priors - array of prior log probabilities over each state
  - gmm.means  - matrix of means (column x is mean of component x)
  - gmm.covars - matrix of covariances (column x is the diagonal of the
                 covariance matrix of component x)

** HMM with GMM observations (does not work with all functions)
  - hmm.name          - 
  - hmm.nstates       - number of states in the HMM
  - hmm.emission_type - 'GMM'
  - hmm.start_prob    - array of log probs P(first observation is state x)
  - hmm.end_prob      - array of log probs P(last observation is state x)
  - hmm.transmat      - matrix of transition log probs (transmat(x,y) 
                        = log(P(transition from state x to state y)))
  - hmm.labels        - optional cell array of labels for each state in the HMM
                        (for use in composing HMMs)
  - hmm.gmms          - array of GMM structures 

** HMM with Gaussian observations
  - hmm.nstates       - number of states in the HMM
  - hmm.emission_type - 'gaussian'
  - hmm.start_prob    - array of log probs P(first observation is state x)
  - hmm.end_prob      - array of log probs P(last observation is state x)
  - hmm.transmat      - matrix of transition log probs (transmat(x,y) 
                        = log(P(transition from state x to state y)))
  - hmm.labels        - optional cell array of labels for each state in the HMM
                        (for use in composing HMMs)
  - hmm.means         - matrix of means (column x is mean of state x)
  - hmm.covars        - matrix of means (column x is the diagonal of the
                        covariance matrix of component x)

Note that each row of exp(hmm.transmat) does not necessarily sum to 1
because for each state x there is some probability
(exp(hmm.end_prob(x))) that the next transition will be to a
non-emitting exit state (i.e. the current observation is the last
observation in the sequence).  The correct invariant is:
sum(exp(hmm.transmat), 2)' + exp(hmm.end_prob) == ones(hmm.nstates, 1)

2007-11-06 Ron Weiss <ronw@ee.columbia.edu>