{"id":5247,"library":"hmmlearn","title":"hmmlearn","description":"hmmlearn is a Python library for unsupervised learning of Hidden Markov Models (HMMs) with an API designed to be compatible with scikit-learn. It includes implementations for Gaussian HMMs, Multinomial HMMs, and GMM-HMMs. The current version is 0.3.3, and it receives updates for bug fixes and compatibility, though major feature releases are infrequent.","status":"active","version":"0.3.3","language":"en","source_language":"en","source_url":"https://github.com/hmmlearn/hmmlearn","tags":["machine-learning","hidden-markov-model","HMM","scikit-learn-api","unsupervised-learning","sequence-modeling"],"install":[{"cmd":"pip install hmmlearn","lang":"bash","label":"Install hmmlearn"}],"dependencies":[{"reason":"Core numerical operations.","package":"numpy","optional":false},{"reason":"Scientific computing operations.","package":"scipy","optional":false},{"reason":"Provides k-means for initialization and other utilities, and API compatibility.","package":"scikit-learn","optional":false}],"imports":[{"symbol":"GaussianHMM","correct":"from hmmlearn import hmm\nmodel = hmm.GaussianHMM(...)"},{"symbol":"MultinomialHMM","correct":"from hmmlearn import hmm\nmodel = hmm.MultinomialHMM(...)"},{"symbol":"GMMHMM","correct":"from hmmlearn import hmm\nmodel = hmm.GMMHMM(...)"}],"quickstart":{"code":"import numpy as np\nfrom hmmlearn import hmm\n\n# 1. Generate some sample data\n# Let's create data that has two underlying 'states' with different means\n# The HMM will try to discover these.\nnp.random.seed(42)\nX = np.concatenate([np.random.randn(100, 1) + 0,\n                    np.random.randn(100, 1) + 5])\n# Mix the data to simulate a sequence, important for HMMs\nnp.random.shuffle(X)\n\n# 2. Create and train a Gaussian HMM model\n# n_components: number of hidden states we want to find\n# covariance_type: \"full\", \"tied\", \"diag\", \"spherical\"\n# n_iter: number of EM iterations to perform\nmodel = hmm.GaussianHMM(n_components=2, covariance_type=\"full\", n_iter=100, random_state=42)\n\n# The 'fit' method estimates parameters from data using the EM algorithm.\n# If initial parameters are not set, 'hmmlearn' will use k-means to initialize.\nmodel.fit(X)\n\n# 3. Predict the hidden states for the observed data\nhidden_states = model.predict(X)\n\nprint(\"Learned Means:\\n\", model.means_)\nprint(\"Learned Transition Matrix:\\n\", model.transmat_)\nprint(\"First 10 hidden states:\\n\", hidden_states[:10])\n\n# 4. Score the model (log-likelihood of the data given the model)\nscore = model.score(X)\nprint(\"\\nModel score (log-likelihood):\", score)\n\n# 5. Generate new samples from the learned model\nX_new, Z_new = model.sample(n_samples=50)\nprint(\"\\nShape of new samples:\", X_new.shape)\nprint(\"First 5 new samples:\\n\", X_new[:5].T)\nprint(\"First 5 new hidden states:\\n\", Z_new[:5])","lang":"python","description":"This quickstart demonstrates how to create, train, and use a Gaussian Hidden Markov Model (HMM). It covers generating sample data, fitting the HMM, predicting hidden states, scoring the model, and sampling new sequences from the learned model."},"warnings":[{"fix":"Ensure all observations passed to `MultinomialHMM` are integers. If your data is continuous, consider binning it or using `GaussianHMM` or `GMMHMM`.","message":"The `MultinomialHMM` class from version 0.2.0 onwards requires integer-valued observations (e.g., `[0, 1, 2, 1]`). Prior to 0.2.0, it could implicitly handle float-like inputs by converting them. Passing non-integer data to `MultinomialHMM` in current versions will raise an error.","severity":"breaking","affected_versions":"<0.2.0 -> >=0.2.0"},{"fix":"For `MultinomialHMM`, ensure `X` is an array of integers. For `n_features=1`, `X` should be `(n_samples,)` or `(n_samples, 1)`. If `X` contains multiple categorical features, it should be `(n_samples, n_features)` where each feature column is integers.","message":"The expected input data shape for `MultinomialHMM` can be confusing. For a single sequence of observations, it expects a 1D array of integers `(n_samples,)` if `n_features` is effectively 1, or `(n_samples, n_features)` where each `n_features` element is an integer, rather than a 2D array of floats `(n_samples, n_features)` as is common for `GaussianHMM`.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Run the `fit` method multiple times with different `random_state` values, select the model with the highest `score` (log-likelihood), or increase `n_iter` for more iterations. Consider using initial parameter estimates if domain knowledge is available.","message":"HMM fitting with the Expectation-Maximization (EM) algorithm can converge to local optima rather than the global optimum. This can lead to suboptimal model parameters and poor performance.","severity":"gotcha","affected_versions":"All"},{"fix":"Review the documentation for `init_params` (default: 'ste' for 's'tartprob, 't'ransmat, 'e'missionprob, 'm'eans, 'c'ovars) and `params` (default: 'ste' or 'stmc' depending on the model) for the specific HMM type you are using. Explicitly set these if you wish to fix certain parameters or provide custom initialization.","message":"The `init_params` and `params` arguments in the model's constructor control which parameters are initialized automatically and which are estimated during `fit`. Misunderstanding their usage can lead to errors or parameters not being estimated as expected.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}