ix-hmm

name	ix-hmm
description	Hidden Markov Model analysis — Viterbi, Baum-Welch, forward-backward
disable-model-invocation	true

HMM Analysis

Decode hidden state sequences, learn model parameters, compute state probabilities.

When to Use

When the user has sequential observations generated by an unknown underlying process — speech recognition, NLP tagging, biological sequences, regime detection in finance.

Algorithms

• Viterbi — Most likely hidden state sequence (MAP path)
• Forward — Total probability of observation sequence P(O|model)
• Forward-Backward — Posterior probability of each state at each time step
• Baum-Welch — Learn HMM parameters (initial, transition, emission) from observations via EM
• MAP Estimate — Most probable state at each time independently

Programmatic Usage

use ix_graph::hmm::HiddenMarkovModel;
use ndarray::{array, Array2};

let hmm = HiddenMarkovModel::new(
    initial,       // Array1<f64> — prior state distribution
    transition,    // Array2<f64> — state-to-state transition probs
    emission,      // Array2<f64> — state-to-observation emission probs
).unwrap();

let (path, log_prob) = hmm.viterbi(&observations);
let log_likelihood = hmm.forward(&observations);
let gamma = hmm.forward_backward(&observations);  // posterior state probs
let trained = hmm.baum_welch(&observations, 100, 1e-6);  // EM learning

Tips

• Viterbi works in log-space to avoid numerical underflow
• Baum-Welch converges to local optima — try multiple random initializations
• Forward-backward gamma[t][i] = P(state=i at time t | all observations)