## Contents

- Description
- Usage with known observation and transition probability matrix: Viterbi
- Usage with unknown parameters: Baum Welch (EM) algorithm

## Description

Demonstrates parameter learning and inference on Hidden Markov Models using classic problem setup of a Casino that switches out a fair die for a loaded die

    close all
    clear all

    % ----- Generate Sequence Data --------------------------------------------
    % "Occassionally dishonest casino" example
    O = [1/6 , 1/6 , 1/6 , 1/6 , 1/6 , 1/6  ;  ... % fair die
         1/10, 1/10, 1/10, 1/10, 1/10, 5/10 ];   % loaded die
    T = [1/2 , 1/2; 1/4, 3/4];
    pi = [1/2, 1/2];
    len = 25;
    numSeq = 1;
    seq = ml_sampleMC(T, pi, numSeq, len);
    X = zeros(numSeq, len);
    % generate observation states from distribution at each hidden state
    for k = 1:len
        for p = 1:numSeq
            X(p, k) = ml_randSampleDiscrete(O(seq(k), :));
        end
    end

## Usage with known observation and transition probability matrix: Viterbi

    options_hmm = [];
    options_hmm.observed = O;
    options_hmm.transition = T;
    options_hmm.pi = pi;
    model_hmm = ml_unsupervised_HMM(X, options_hmm);
    viterbiSeq = model_hmm.Viterbi(model_hmm);
    hmmviterbi(X, T, O)
    individuallyBestSeq = model_hmm.individuallyMostLikely(model_hmm);
    disp('Individually most likely latent variable states:')
    disp(individuallyBestSeq);
    disp('True latent variable states:')
    disp(seq)
    disp('Viterbi most likely latent variable sequence:')
    disp(viterbiSeq)
    disp('Misclassification rate for Viterbi:')
    disp(sum(viterbiSeq ~= seq) / length(seq))
    disp('Misclassification rate for Most Likely Individual States:')
    disp(sum(individuallyBestSeq ~= seq) / length(seq))

    ans =

      Columns 1 through 13

         1     1     1     2     2     2     2     2     2     2     2     2     2

      Columns 14 through 25

         2     2     2     2     2     2     2     2     2     2     2     2

    Individually most likely latent variable states:
      Columns 1 through 13

         1     1     1     2     2     2     2     2     1     1     2     2     2

      Columns 14 through 25

         2     2     2     1     1     2     2     2     2     2     2     2

    True latent variable states:
      Columns 1 through 13

         1     1     2     2     2     2     1     1     2     1     2     2     1

      Columns 14 through 25

         2     1     1     1     2     2     2     2     2     2     2     2

    Viterbi most likely latent variable sequence:
      Columns 1 through 13

         1     1     1     2     2     2     2     2     2     2     2     2     2

      Columns 14 through 25

         2     2     2     2     2     2     2     2     2     2     2     2

    Misclassification rate for Viterbi:
        0.3200

    Misclassification rate for Most Likely Individual States:
        0.3200

## Usage with unknown parameters: Baum Welch (EM) algorithm

Learn the parameters of the occassionaly dishonest casino based only on observations and structure assumption

    O = [1/6 , 1/6 , 1/6 , 1/6 , 1/6 , 1/6;  ...  % fair die
         1/10, 1/10, 1/10, 1/10, 1/10, 5/10 ];    % loaded die
    T = [0.50 , 0.50; 0.25, 0.75];
    len = 100; % if len is too short, may not observe something in the sequence
    numSeq = 100;
    seq = ml_sampleMC(T, pi, numSeq, len);
    obs = zeros(numSeq, len);
    [~, seqLen] = size(O);

    % generate observation states from distribution at each hidden state
    X = zeros(numSeq, len);
    for k = 1:len
        for p = 1:numSeq
            X(p, k) = ml_randSampleDiscrete(O(seq(k), :));
        end
    end

    options_hmm_unknown = [];
    options_hmm_unknown.nHiddenStatesGuess = 2;
    options_hmm_unknown.nObservableStatesGuess = 6;
    model_hmm_unknown = ml_unsupervised_HMM(X, options_hmm_unknown);
    [Ohat, That] = model_hmm_unknown.BaumWelch(model_hmm_unknown);
    disp('True emission probabilities:')
    disp(O);
    disp('Learned emissions probabilities:')
    disp(Ohat);
    disp('True transition probabilities:')
    disp(T);
    disp('Learned transition probabilities:')
    disp(That);

    True emission probabilities:
        0.1667    0.1667    0.1667    0.1667    0.1667    0.1667
        0.1000    0.1000    0.1000    0.1000    0.1000    0.5000

    Learned emissions probabilities:
        0.1209    0.0911    0.2109    0.0637    0.1644    0.3489
        0.1533    0.1888    0.0206    0.2192    0.0869    0.3312

    True transition probabilities:
        0.5000    0.5000
        0.2500    0.7500

    Learned transition probabilities:
        0.4942    0.5058
        0.6758    0.3242