HiddenMarkovModels.jl

A Julia package for simulation, inference and learning of Hidden Markov Models with discrete states and discrete time.

Getting started

This package can be installed using Julia's package manager:

pkg> add HiddenMarkovModels

Then, you can create your first model as follows:

using Distributions, HiddenMarkovModels
init = [0.6, 0.4]
trans = [0.7 0.3; 0.2 0.8]
dists = [Normal(-1.0), Normal(1.0)]
hmm = HMM(init, trans, dists)

Take a look at the documentation to know what to do next!

Some background

Hidden Markov Models (HMMs) are a widely used modeling framework in signal processing, bioinformatics and plenty of other fields. They explain an observation sequence $(Y_t)$ by assuming the existence of a latent Markovian state sequence $(X_t)$ whose current value determines the distribution of observations. In some scenarios, the state and the observation sequence are also allowed to depend on a known control sequence $(U_t)$. Each of the problems below has an efficient solution algorithm, available here:

Problem	Goal	Algorithm
Evaluation	Likelihood of the observation sequence	Forward
Filtering	Last state marginals	Forward
Smoothing	All state marginals	Forward-backward
Decoding	Most likely state sequence	Viterbi
Learning	Maximum likelihood parameter	Baum-Welch

Take a look at this tutorial to know more about the math:

A tutorial on hidden Markov models and selected applications in speech recognition, Rabiner (1989)

Main features

This package is generic. Observations can be arbitrary Julia objects, not just scalars or arrays. Number types are not restricted to floating point, which enables automatic differentiation. Time-dependent or controlled HMMs are supported out of the box.

This package is fast. All the inference functions have allocation-free versions, which leverage efficient linear algebra subroutines. We will include extensive benchmarks against Julia and Python competitors.

This package is reliable. It gives the same results as the previous reference package up to numerical accuracy. The test suite incorporates quality checks as well as type stability and allocation analysis.

Citation

If this package is useful to your research, please cite the JOSS paper. Here is the BibTeX key:

@article{
    Dalle2024,
    doi = {10.21105/joss.06436},
    url = {https://doi.org/10.21105/joss.06436},
    year = {2024},
    publisher = {The Open Journal},
    volume = {9},
    number = {96},
    pages = {6436},
    author = {Guillaume Dalle},
    title = {HiddenMarkovModels.jl: generic, fast and reliable state space modeling},
    journal = {Journal of Open Source Software}
}

Contributing

If you spot a bug or want to ask about a new feature, please open an issue on the GitHub repository. Once the issue receives positive feedback, feel free to try and fix it with a pull request that follows the BlueStyle guidelines.

Acknowledgements

A big thank you to Maxime Mouchet and Jacob Schreiber, the respective lead devs of alternative packages HMMBase.jl and pomegranate, for their help and advice. Logo by Clément Mantoux based on a portrait of Andrey Markov.