Module bio::stats::hmm

An implementation of Hidden Markov Models in Rust.

Examples

Discrete Emission Distribution

We construct the example from Borodovsky & Ekisheva (2006), pp. 80 (also see these slides.

#[macro_use] extern crate approx;
#[macro_use] extern crate ndarray;

use bio::stats::Prob;
use bio::stats::hmm::discrete_emission::Model as DiscreteEmissionHMM;
use bio::stats::hmm::viterbi;

let transition = array![[0.5, 0.5], [0.4, 0.6]];
let observation = array![[0.2, 0.3, 0.3, 0.2], [0.3, 0.2, 0.2, 0.3]];
let initial = array![0.5, 0.5];

let hmm = DiscreteEmissionHMM::with_float(&transition, &observation, &initial)
    .expect("Dimensions should be consistent");
let (path, log_prob) = viterbi(&hmm, &vec![2, 2, 1, 0, 1, 3, 2, 0, 0]);
let prob = Prob::from(log_prob);
assert_relative_eq!(4.25e-8_f64, *prob, epsilon = 1e-9_f64);

Continuous (Gaussian) Emission Distribution

#[macro_use] extern crate approx;
#[macro_use] extern crate ndarray;

use bio::stats::Prob;
use bio::stats::hmm::univariate_continuous_emission::GaussianModel as GaussianHMM;
use statrs::distribution::Normal;
use bio::stats::hmm::viterbi;

let transition = array![[0.5, 0.5], [0.4, 0.6]];
let observation = vec![
    Normal::new(0.0, 1.0).unwrap(),
    Normal::new(2.0, 1.0).unwrap(),
];
let initial = array![0.5, 0.5];

let hmm = GaussianHMM::with_float(&transition, observation, &initial)
    .expect("Dimensions should be consistent");
let (path, log_prob) = viterbi(
    &hmm,
    &vec![-0.1, 0.1, -0.2, 0.5, 0.8, 1.1, 1.2, 1.5, 0.5, 0.2],
);
let prob = Prob::from(log_prob);
assert_relative_eq!(2.64e-8_f64, *prob, epsilon = 1e-9_f64);

Numeric Stability

The implementation uses log-scale probabilities for numeric stability.

Limitations

Currently, only discrete and single-variate Gaussian continuous HMMs are implemented. Also, only dense transition matrices are supported.

References

• Rabiner, Lawrence R. "A tutorial on hidden Markov models and selected applications in speech recognition." Proceedings of the IEEE 77, no. 2 (1989): 257-286.

Modules

discrete_emission	Implementation of Hidden Markov Model with emission values from discrete distributions.
univariate_continuous_emission	Implementation of Hidden Markov Models with emission values from univariate continuous distributions.

Structs

State	A newtype for HMM states.
StateIter	Iterate over the states of a Model.
StateTransition	Transition between two states in a Model.
StateTransitionIter	Iterate over all state transitions of a Model.

Enums

HMMError

Traits

Model

A trait for Hidden Markov Models (HMM) with generic Observation type.

Functions

backward	Execute the backward algorithm and return the backward probabilities as LogProb values and the resulting backward probability.
forward	Execute the forward algorithm and return the forward probabilites as LogProb values and the resulting forward probability.
viterbi	Execute Viterbi algorithm on the given slice of Observation values to get the maximum a posteriori (MAP) probability.