Skip to main content

hmmlearn/
lib.rs

1//! `hmmlearn` — a native Rust port of the Python library `hmmlearn`.
2//!
3//! Hidden Markov Models with categorical, Gaussian, Gaussian-mixture, Poisson,
4//! and multinomial emissions, trained by Expectation–Maximization or variational
5//! inference.
6//!
7//! Fitting proceeds by Expectation–Maximization (maximum-likelihood) or
8//! mean-field variational inference. The concrete models and their builders live
9//! in [`models`], backed by the forward–backward and Viterbi routines in
10//! [`core`], the covariance representations in [`covariance`], and the
11//! supporting numerics (special functions, linear algebra, statistics, and array
12//! utilities) in the remaining modules.
13//!
14//! # Quick start
15//!
16//! Every model is built with a fluent builder, fit with
17//! [`fit`](models::GaussianHmm::fit), and returns a [`Fitted`](core::Fitted)
18//! handle exposing `predict`, `score`, `sample`, `decode`, `aic`/`bic`, and the
19//! learned parameters.
20//!
21//! ```
22//! use hmmlearn::models::GaussianHmm;
23//! use hmmlearn::ndarray::array;
24//!
25//! // One feature per column; each row is an observation.
26//! let x = array![[0.0], [0.2], [-0.1], [5.0], [5.2], [4.8]];
27//!
28//! let model = GaussianHmm::new(2)
29//!     .n_iter(20)
30//!     .random_state(42)
31//!     .fit(x.view(), None)?;
32//!
33//! let states = model.predict(x.view(), None)?;
34//! assert_eq!(states.len(), x.nrows());
35//!
36//! let log_likelihood = model.score(x.view(), None)?;
37//! assert!(log_likelihood.is_finite());
38//! # Ok::<(), hmmlearn::HmmError>(())
39//! ```
40//!
41//! Multiple independent sequences are concatenated along the rows and delimited
42//! by a `lengths` slice, exactly as in `hmmlearn`:
43//! `model.fit(x.view(), Some(&[100, 200, 150]))`.
44//!
45//! # Relationship to `hmmlearn`
46//!
47//! This is a faithful, pure-Rust port of
48//! [`hmmlearn`](https://github.com/hmmlearn/hmmlearn) 0.3.3 with no LAPACK/BLAS
49//! dependency. It deviates from upstream in three documented, test-validated
50//! ways, all confined to initialization and sampling: k-means++ replaces
51//! scikit-learn's `KMeans` for mean initialization; multivariate-normal sampling
52//! uses a Cholesky factor rather than NumPy's SVD; and the binomial sampler omits
53//! NumPy's BTPE branch in favor of the inversion fallback. Fitted parameters and
54//! inference results match upstream.
55
56pub use ndarray;
57
58pub mod cluster;
59pub mod core;
60pub mod covariance;
61pub mod error;
62pub mod kl;
63pub mod linalg;
64pub mod models;
65pub mod rng;
66pub mod special;
67pub mod stats;
68pub mod util;
69
70#[cfg(test)]
71pub(crate) mod testutil;
72
73pub use error::{HmmError, Result};