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.