hmmlearn

https://hmmlearn.readthedocs.io/en/stable/
Admin
hmmlearn is a Python library for unsupervised learning and inference of Hidden Markov Models with...
Tokens:78,368
Snippets:423
Trust Score:9.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Setup and training loop for VI and EM HMM comparison

Source: https://hmmlearn.readthedocs.io/en/stable/_downloads/2e3b08813331975e37208fccac03cf8c/plot_variational_inference.ipynb

Imports and defines a helper function to visualize HMM parameters, then sets up a 4-state GaussianHMM and generates training data. It also starts a loop that trains VariationalGaussianHMM and GaussianHMM models for different numbers of states, tracking the best model by variational lower bound.

```python
import collections
import numpy as np
import matplotlib.pyplot as plt
import matplotlib.gridspec as gs
import scipy.stats

from sklearn.utils import check_random_state

from hmmlearn import hmm, vhmm
import matplotlib


def gaussian_hinton_diagram(startprob, transmat, means,
                            variances, vmin=0, vmax=1, infer_hidden=True):
    """
    Show the initial state probabilities, the transition probabilities
    as heatmaps, and draw the emission distributions.
    """

    num_states = transmat.shape[0]

    f = plt.figure(figsize=(3*(num_states), 2*num_states))
    grid = gs.GridSpec(3, 3)

    ax = f.add_subplot(grid[0, 0])
    ax.imshow(startprob[None, :], vmin=vmin, vmax=vmax)
    ax.set_title("Initial Probabilities", size=14)

    ax = f.add_subplot(grid[1:, 0])
    ax.imshow(transmat, vmin=vmin, vmax=vmax)
    ax.set_title("Transition Probabilities", size=14)

    ax = f.add_subplot(grid[1:, 1:])
    for i in range(num_states):
        keep = True
        if infer_hidden:
            if np.all(np.abs(transmat[i] - transmat[i][0]) < 1e-4):
                keep = False
        if keep:
            s_min = means[i] - 10 * variances[i]
            s_max = means[i] + 10 * variances[i]
            xx = np.arange(s_min, s_max, (s_max - s_min) / 1000)
            norm = scipy.stats.norm(means[i], np.sqrt(variances[i]))
            yy = norm.pdf(xx)
            keep = yy > .01
            ax.plot(xx[keep], yy[keep], label="State: {}".format(i))
    ax.set_title("Emissions Probabilities", size=14)
    ax.legend(loc="best")
    f.tight_layout()
    return f

np.set_printoptions(formatter={'float_kind': "{:.3f}".format})
rs = check_random_state(2022)
sample_length = 500
num_samples = 1
# With random initialization, it takes a few tries to find the
# best solution
num_inits = 5
num_states = np.arange(1, 7)
verbose = False


# Prepare parameters for a 4-components HMM
# And Sample several sequences from this model
model = hmm.GaussianHMM(4, init_params="")
model.n_features = 4
# Initial population probability
model.startprob_ = np.array([0.25, 0.25, 0.25, 0.25])
# The transition matrix, note that there are no transitions possible
# between component 1 and 3
model.transmat_ = np.array([[0.2, 0.2, 0.3, 0.3],
                            [0.3, 0.2, 0.2, 0.3],
                            [0.2, 0.3, 0.3, 0.2],
                            [0.3, 0.3, 0.2, 0.2]])
# The means and covariance of each component
model.means_ = np.array([[-1.5],
                         [0],
                         [1.5],
                         [3.]])
model.covars_ = np.array([[0.25],
                          [0.25],
                          [0.25],
                          [0.25]])**2

# Generate training data
sequences = []
lengths = []

for i in range(num_samples):
    sequences.extend(model.sample(sample_length, random_state=rs)[0])
    lengths.append(sample_length)
sequences = np.asarray(sequences)

# Train a suite of models, and keep track of the best model for each
# number of states, and algorithm
best_scores = collections.defaultdict(dict)
best_models = collections.defaultdict(dict)
for n in num_states:
    for i in range(num_inits):
        vi = vhmm.VariationalGaussianHMM(n,
                                         n_iter=1000,
                                         covariance_type="full",
                                         implementation="scaling",
                                         tol=1e-6,
                                         random_state=rs,
                                         verbose=verbose)
        vi.fit(sequences, lengths)
        lb = vi.monitor_.history[-1]
        print(f"Training VI({n}) Variational Lower Bound={lb} "
              f"Iterations={len(vi.monitor_.history)} ")
        if best_models["VI"].get(n) is None or best_scores["VI"][n] < lb:
            best_models["VI"][n] = vi
            best_scores["VI"][n] = lb

        em = hmm.GaussianHMM(n,
                         
```

--------------------------------

### Multinomial HMM example: setup, fit, decode, and refit

Source: https://hmmlearn.readthedocs.io/en/stable/auto_examples/plot_multinomial_hmm.html

This snippet demonstrates the full workflow of using hmmlearn's MultinomialHMM: defining states, probabilities, and observations, converting sentences to counts, fitting the model, decoding sequences, and printing learned parameters. It also shows how to reset and refit the model with different initialization parameters ('ste' instead of '').

```python
import numpy as np
from hmmlearn import hmm

# For this example, we will model the stages of a conversation,
# where each sentence is "generated" with an underlying topic, "cat" or "dog"
states = ["cat", "dog"]
id2topic = dict(zip(range(len(states)), states))
# we are more likely to talk about cats first
start_probs = np.array([0.6, 0.4])

# For each topic, the probability of saying certain words can be modeled by
# a distribution over vocabulary associated with the categories

vocabulary = ["tail", "fetch", "mouse", "food"]
# if the topic is "cat", we are more likely to talk about "mouse"
# if the topic is "dog", we are more likely to talk about "fetch"
emission_probs = np.array([[0.25, 0.1, 0.4, 0.25],
                           [0.2, 0.5, 0.1, 0.2]])

# Also assume it's more likely to stay in a state than transition to the other
trans_mat = np.array([[0.8, 0.2], [0.2, 0.8]])


# Pretend that every sentence we speak only has a total of 5 words,
# i.e. we independently utter a word from the vocabulary 5 times per sentence
# we observe the following bag of words (BoW) for 8 sentences:
observations = [["tail", "mouse", "mouse", "food", "mouse"],
        ["food", "mouse", "mouse", "food", "mouse"],
        ["tail", "mouse", "mouse", "tail", "mouse"],
        ["food", "mouse", "food", "food", "tail"],
        ["tail", "fetch", "mouse", "food", "tail"],
        ["tail", "fetch", "fetch", "food", "fetch"],
        ["fetch", "fetch", "fetch", "food", "tail"],
        ["food", "mouse", "food", "food", "tail"],
        ["tail", "mouse", "mouse", "tail", "mouse"],
        ["fetch", "fetch", "fetch", "fetch", "fetch"]]

# Convert "sentences" to numbers:
vocab2id = dict(zip(vocabulary, range(len(vocabulary))))
def sentence2counts(sentence):
    ans = []
    for word, idx in vocab2id.items():
        count = sentence.count(word)
        ans.append(count)
    return ans

X = []
for sentence in observations:
    row = sentence2counts(sentence)
    X.append(row)

data = np.array(X, dtype=int)

# pretend this is repeated, so we have more data to learn from:
lengths = [len(X)]*5
sequences = np.tile(data, (5,1))


# Set up model:
model = hmm.MultinomialHMM(n_components=len(states),
        n_trials=len(observations[0]),
        n_iter=50,
        init_params='')

model.n_features = len(vocabulary)
model.startprob_ = start_probs
model.transmat_ = trans_mat
model.emissionprob_ = emission_probs
model.fit(sequences, lengths)
logprob, received = model.decode(sequences)

print("Topics discussed:")
print([id2topic[x] for x in received])

print("Learned emission probs:")
print(model.emissionprob_)

print("Learned transition matrix:")
print(model.transmat_)

# Try to reset and refit:
new_model = hmm.MultinomialHMM(n_components=len(states),
        n_trials=len(observations[0]),
        n_iter=50, init_params='ste')

new_model.fit(sequences, lengths)
logprob, received = new_model.decode(sequences)

print("\nNew Model")
print("Topics discussed:")
print([id2topic[x] for x in received])

print("Learned emission probs:")
print(new_model.emissionprob_)

print("Learned transition matrix:")
print(new_model.transmat_)
```

--------------------------------

### Define Multinomial HMM parameters

Source: https://hmmlearn.readthedocs.io/en/stable/_sources/auto_examples/plot_multinomial_hmm.rst.txt

Sets up a Multinomial HMM example with two topics ("cat" and "dog"), a vocabulary of four words, and manually defined start probabilities, emission probabilities, and transition matrix. The comments explain the modeling choices: cats are more likely to be the first topic, "mouse" is more likely under "cat", "fetch" under "dog", and staying in a state is more likely than transitioning.

```Python
import numpy as np
from hmmlearn import hmm

# For this example, we will model the stages of a conversation,
# where each sentence is "generated" with an underlying topic, "cat" or "dog"
states = ["cat", "dog"]
id2topic = dict(zip(range(len(states)), states))
# we are more likely to talk about cats first
start_probs = np.array([0.6, 0.4])

# For each topic, the probability of saying certain words can be modeled by
# a distribution over vocabulary associated with the categories

vocabulary = ["tail", "fetch", "mouse", "food"]
# if the topic is "cat", we are more likely to talk about "mouse"
# if the topic is "dog", we are more likely to talk about "fetch"
emission_probs = np.array([[0.25, 0.1, 0.4, 0.25],
                           [0.2, 0.5, 0.1, 0.2]])

# Also assume it's more likely to stay in a state than transition to the other
trans_mat = np.array([[0.8, 0.2], [0.2, 0.8]])
```

--------------------------------

### Import required modules for HMM example

Source: https://hmmlearn.readthedocs.io/en/stable/_sources/auto_examples/plot_casino.rst.txt

Imports numpy, matplotlib.pyplot, and the hmm module from hmmlearn, which are required for the dishonest casino example.

```Python
import numpy as np
import matplotlib.pyplot as plt

from hmmlearn import hmm

```

--------------------------------

### Set up random state and model parameters

Source: https://hmmlearn.readthedocs.io/en/stable/_sources/auto_examples/plot_variational_inference.rst.txt

Configures random state, sample length, number of samples, and number of initializations. Defines a 4-component GaussianHMM with specified start probabilities, transition matrix, means, and covariances.

```python
    np.set_printoptions(formatter={'float_kind': "{:.3f}".format})
    rs = check_random_state(2022)
    sample_length = 500
    num_samples = 1
    # With random initialization, it takes a few tries to find the
    # best solution
    num_inits = 5
    num_states = np.arange(1, 7)
    verbose = False


    # Prepare parameters for a 4-components HMM
    # And Sample several sequences from this model
    model = hmm.GaussianHMM(4, init_params="")
    model.n_features = 4
    # Initial population probability
    model.startprob_ = np.array([0.25, 0.25, 0.25, 0.25])
    # The transition matrix, note that there are no transitions possible
    # between component 1 and 3
    model.transmat_ = np.array([[0.2, 0.2, 0.3, 0.3],
                                [0.3, 0.2, 0.2, 0.3],
                                [0.2, 0.3, 0.3, 0.2],
                                [0.3, 0.3, 0.2, 0.2]])
    # The means and covariance of each component
    model.means_ = np.array([[-1.5],
                             [0],
                             [1.5],
                             [3.]])
    model.covars_ = np.array([[0.25],
                              [0.25],
                              [0.25],
                              [0.25]])**2
```

--------------------------------

### Sample from a GaussianHMM with manually set parameters

Source: https://hmmlearn.readthedocs.io/en/stable/_downloads/9d87b4c2b3bd78318d48ac9aef2f54be/plot_hmm_sampling_and_decoding.ipynb

Sets up a 4-component GaussianHMM with explicit start probabilities, transition matrix, means, and covariances, then samples 500 observations and plots them with component labels. The transition matrix intentionally has no transitions between component 1 and 3.

```python
import numpy as np
import matplotlib.pyplot as plt

from hmmlearn import hmm

# Prepare parameters for a 4-components HMM
# Initial population probability
startprob = np.array([0.6, 0.3, 0.1, 0.0])
# The transition matrix, note that there are no transitions possible
# between component 1 and 3
transmat = np.array([[0.7, 0.2, 0.0, 0.1],
                     [0.3, 0.5, 0.2, 0.0],
                     [0.0, 0.3, 0.5, 0.2],
                     [0.2, 0.0, 0.2, 0.6]])
# The means of each component
means = np.array([[0.0, 0.0],
                  [0.0, 11.0],
                  [9.0, 10.0],
                  [11.0, -1.0]])
# The covariance of each component
covars = .5 * np.tile(np.identity(2), (4, 1, 1))

# Build an HMM instance and set parameters
gen_model = hmm.GaussianHMM(n_components=4, covariance_type="full")

# Instead of fitting it from the data, we directly set the estimated
# parameters, the means and covariance of the components
gen_model.startprob_ = startprob
gen_model.transmat_ = transmat
gen_model.means_ = means
gen_model.covars_ = covars

# Generate samples
X, Z = gen_model.sample(500)

# Plot the sampled data
fig, ax = plt.subplots()
ax.plot(X[:, 0], X[:, 1], ".-", label="observations", ms=6,
        mfc="orange", alpha=0.7)

# Indicate the component numbers
for i, m in enumerate(means):
    ax.text(m[0], m[1], 'Component %i' % (i + 1),
            size=17, horizontalalignment='center',
            bbox=dict(alpha=.7, facecolor='w'))
ax.legend(loc='best')
fig.show()
```

--------------------------------

### ConvergenceMonitor

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Documentation for the ConvergenceMonitor class, including its constructor, properties, methods, and an example of subclassing.

```APIDOC
## ConvergenceMonitor

### Description
Monitor and report convergence to `sys.stderr`.

### Constructor
`ConvergenceMonitor(tol, n_iter, verbose)`

### Parameters
- **tol** (double) - Required - Convergence threshold. EM has converged either if the maximum number of iterations is reached or the log probability improvement between the two consecutive iterations is less than threshold.
- **n_iter** (int) - Required - Maximum number of iterations to perform.
- **verbose** (bool) - Required - Whether per-iteration convergence reports are printed.

### Properties
- **converged** (bool) - Whether the EM algorithm converged.

### Methods
#### report(log_prob)
Report convergence to `sys.stderr`. The output consists of three columns: iteration number, log probability of the data at the current iteration and convergence rate. At the first iteration convergence rate is unknown and is thus denoted by NaN.

##### Parameters
- **log_prob** (float) - Required - The log probability of the data as computed by EM algorithm in the current iteration.

### Variables
- **history** (deque) - The log probability of the data for the last two training iterations. If the values are not strictly increasing, the model did not converge.
- **iter** (int) - Number of iterations performed while training the model.

### Example
```python
>>> from hmmlearn.base import ConvergenceMonitor
>>> from hmmlearn import hmm
>>>
>>> class ThresholdMonitor(ConvergenceMonitor):
...     @property
...     def converged(self):
...         return (self.iter == self.n_iter or
...                 self.history[-1] >= self.tol)
>>>
>>> model = hmm.GaussianHMM(n_components=2, tol=5, verbose=True)
>>> model.monitor_ = ThresholdMonitor(model.monitor_.tol,
...                                   model.monitor_.n_iter,
...                                   model.monitor_.verbose)
```
```

--------------------------------

### Explicitly initialize transition matrix with init_params

Source: https://hmmlearn.readthedocs.io/en/stable/tutorial.html

Explicitly initialize the transition probability matrix by omitting 't' from init_params and setting transmat_ before training. The model will use the provided matrix as the starting point for EM.

```python
>>> model = hmm.GaussianHMM(n_components=3, n_iter=100, init_params="mcs")
>>> model.transmat_ = np.array([[0.7, 0.2, 0.1],
...                             [0.3, 0.5, 0.2],
...                             [0.3, 0.3, 0.4]])
```

--------------------------------

### VariationalGaussianHMM

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Documentation for the VariationalGaussianHMM class, including its constructor parameters, attributes, and a usage example.

```APIDOC
## VariationalGaussianHMM

### Description
VariationalGaussianHMM is a Hidden Markov Model with Gaussian emissions, using variational inference for parameter estimation. It supports multiple covariance types and provides priors and posteriors for model parameters.

### Constructor
`__init__(n_components=1, covariance_type='full', startprob_prior=None, transmat_prior=None, means_prior=None, beta_prior=None, dof_prior=None, scale_prior=None, algorithm='viterbi', random_state=None, n_iter=100, tol=1e-06, verbose=False, params='stmc', init_params='stmc', implementation='log')`

### Parameters
- **n_components** (int, optional) – Number of states in the model. Default is 1.
- **covariance_type** (str, optional) – Type of covariance parameters to use. Must be one of 'spherical', 'diag', 'full', or 'tied'. Default is 'full'.
- **startprob_prior** (array, shape (n_components,), optional) – Prior for the initial state occupation distribution.
- **transmat_prior** (array, shape (n_components, n_components), optional) – Prior for the matrix of transition probabilities between states.
- **means_prior** (array, shape (n_components, n_features), optional) – Prior estimates for the mean of each state.
- **beta_prior** (array, shape (n_components,), optional) – Prior estimate on the scale of the variance over the means.
- **dof_prior** (int or array, optional) – Prior on the Degrees Of Freedom for each state's Wishart distribution. Type depends on covariance_type.
- **scale_prior** (array, optional) – Prior for the Inverse scale parameter for each state's Wishart distribution.
- **algorithm** (str, optional) – Decoder algorithm. Default is 'viterbi'.
- **random_state** (int or RandomState, optional) – Random seed for reproducibility.
- **n_iter** (int, optional) – Maximum number of iterations to perform. Default is 100.
- **tol** (float, optional) – Convergence threshold. Default is 1e-06.
- **verbose** (bool, optional) – Whether to print convergence information. Default is False.
- **params** (str, optional) – Which parameters to update during training. Default is 'stmc'.
- **init_params** (str, optional) – Which parameters to initialize before training. Default is 'stmc'.
- **implementation** (str, optional) – Implementation to use for computations. Default is 'log'.

### Attributes
- **n_features** (int) – Dimensionality of the Gaussian emissions.
- **monitor** (ConvergenceMonitor) – Monitor object used to check the convergence of EM.
- **startprob_prior** (array, shape (n_components,)) – Prior for the initial state occupation distribution.
- **startprob_posterior** (array, shape (n_components,)) – Posterior estimate of the state occupation distribution.
- **transmat_prior** (array, shape (n_components, n_components)) – Prior for the matrix of transition probabilities between states.
- **transmat_posterior** (array, shape (n_components, n_components)) – Posterior estimate of the transition probabilities between states.
- **means_prior** (array, shape (n_components, n_features)) – Prior estimates for the mean of each state.
- **means_posterior** (array, shape (n_components, n_features)) – Posterior estimates for the mean of each state.
- **beta_prior** (array, shape (n_components,)) – Prior estimate on the scale of the variance over the means.
- **beta_posterior** (array, shape (n_components,)) – Posterior estimate of the scale of the variance over the means.
- **covars** (array) – Covariance parameters for each state. Shape depends on covariance_type.
- **dof_prior** (int or array) – The Degrees Of Freedom prior for each state's Wishart distribution.
- **dof_posterior** (int or array) – The Degrees Of Freedom for each state's Wishart distribution.
- **scale_prior** (array) – Prior for the Inverse scale parameter for each state's Wishart distribution.
- **scale_posterior** (array) – Inverse scale parameter for each state's wishart distribution.

### Example
```python
>>> from hmmlearn.hmm import VariationalGaussianHMM
>>> VariationalGaussianHMM(n_components=2)  
VariationalGaussianHMM(algorithm='viterbi',...
```
```

--------------------------------

### Set up random state, sample parameters, and generate training data

Source: https://hmmlearn.readthedocs.io/en/stable/auto_examples/plot_variational_inference.html

Configures numpy print options, sets a random seed, defines sample length, number of samples, number of initializations, and number of states to test. Then creates a 4-state GaussianHMM with specified parameters and samples a sequence of length 500.

```python
np.set_printoptions(formatter={'float_kind': "{:.3f}".format})
rs = check_random_state(2022)
sample_length = 500
num_samples = 1
# With random initialization, it takes a few tries to find the
# best solution
num_inits = 5
num_states = np.arange(1, 7)
verbose = False


# Prepare parameters for a 4-components HMM
# And Sample several sequences from this model
model = hmm.GaussianHMM(4, init_params="")
model.n_features = 4
# Initial population probability
model.startprob_ = np.array([0.25, 0.25, 0.25, 0.25])
# The transition matrix, note that there are no transitions possible
# between component 1 and 3
model.transmat_ = np.array([[0.2, 0.2, 0.3, 0.3],
                            [0.3, 0.2, 0.2, 0.3],
                            [0.2, 0.3, 0.3, 0.2],
                            [0.3, 0.3, 0.2, 0.2]])
# The means and covariance of each component
model.means_ = np.array([[-1.5],
                         [0],
                         [1.5],
                         [3.]])
model.covars_ = np.array([[0.25],
                          [0.25],
                          [0.25],
                          [0.25]])**2

# Generate training data
sequences = []
lengths = []

for i in range(num_samples):
    sequences.extend(model.sample(sample_length, random_state=rs)[0])
    lengths.append(sample_length)
sequences = np.asarray(sequences)
```

--------------------------------

### Generate samples continuously with model.sample

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Shows how to generate samples from the model and continue sampling from the last state. The first call discards the feature matrix, the second uses the last state from the previous sequence as the initial state.

```python
# generate samples continuously
_, Z = model.sample(n_samples=10)
X, Z = model.sample(n_samples=10, currstate=Z[-1])

```

--------------------------------

### PoissonHMM.get_metadata_routing

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Gets metadata routing of this object.

```APIDOC
## PoissonHMM.get_metadata_routing

### Description
Gets metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Method
Method

### Returns
- **routing** (MetadataRequest) - A `MetadataRequest` encapsulating routing information.
```

--------------------------------

### MultinomialHMM.get_metadata_routing

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Get metadata routing of this object.

```APIDOC
## MultinomialHMM.get_metadata_routing

### Description
Get metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Method
`get_metadata_routing`

### Returns
- **routing** (MetadataRequest) - A `MetadataRequest` encapsulating routing information.
```

--------------------------------

### GaussianHMM.get_metadata_routing

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Gets metadata routing of this object.

```APIDOC
## GaussianHMM.get_metadata_routing

### Description
Gets metadata routing of this object. Please check User Guide on how the routing mechanism works.

### Method
N/A (SDK method)

### Endpoint
GaussianHMM.get_metadata_routing()

### Returns
- **routing** (MetadataRequest) - A `MetadataRequest` encapsulating routing information.
```

--------------------------------

### Generate samples continuously with GMMHMM.sample

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Shows how to generate samples from a GMMHMM model, first without specifying a current state and then continuing from the last state of the previous sample sequence.

```python
# generate samples continuously
_, Z = model.sample(n_samples=10)
X, Z = model.sample(n_samples=10, currstate=Z[-1])
```

--------------------------------

### VariationalCategoricalHMM

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Documentation for the VariationalCategoricalHMM class, including its constructor, parameters, variables, and an example.

```APIDOC
## VariationalCategoricalHMM

### Description
Hidden Markov Model with categorical (discrete) emissions trained using Variational Inference.

### Constructor
`VariationalCategoricalHMM(n_components=1, startprob_prior=None, transmat_prior=None, emissionprob_prior=None, n_features=None, algorithm='viterbi', random_state=None, n_iter=100, tol=1e-06, verbose=False, params='ste', init_params='ste', implementation='log')`

### Parameters
- **n_components** (int) - Number of states.
- **startprob_prior** (array, shape (n_components,), optional) - Parameters of the Dirichlet prior distribution for `startprob_`.
- **transmat_prior** (array, shape (n_components, n_components), optional) - Parameters of the Dirichlet prior distribution for each row of the transition probabilities `transmat_`.
- **emissionprob_prior** (array, shape (n_components, n_features), optional) - Parameters of the Dirichlet prior distribution for `emissionprob_`.
- **n_features** (int, optional) - The number of categorical symbols in the HMM. Will be inferred from the data if not set.
- **algorithm** ({"viterbi", "map"}, optional) - Decoder algorithm. "viterbi": finds the most likely sequence of states, given all emissions. "map" (also known as smoothing or forward-backward): finds the sequence of the individual most-likely states, given all emissions.
- **random_state** (RandomState or an int seed, optional) - A random number generator instance.
- **n_iter** (int, optional) - Maximum number of iterations to perform.
- **tol** (float, optional) - Convergence threshold. EM will stop if the gain in log-likelihood is below this value.
- **verbose** (bool, optional) - Whether per-iteration convergence reports are printed to `sys.stderr`. Convergence can also be diagnosed using the `monitor_` attribute.
- **params** (string, optional) - The parameters that get updated during (`params`) or initialized before (`init_params`) the training. Can contain any combination of 's' for startprob, 't' for transmat, and 'e' for emissionprob. Defaults to all parameters.
- **init_params** (string, optional) - The parameters that get updated during (`params`) or initialized before (`init_params`) the training. Can contain any combination of 's' for startprob, 't' for transmat, and 'e' for emissionprob. Defaults to all parameters.
- **implementation** (string, optional) - Determines if the forward-backward algorithm is implemented with logarithms ("log"), or using scaling ("scaling"). The default is to use logarithms for backwards compatability.

### Variables
- **n_features** (int) - Number of possible symbols emitted by the model (in the samples).
- **monitor** (ConvergenceMonitor) - Monitor object used to check the convergence of EM.
- **startprob_prior** (array, shape (n_components,)) - Prior for the initial state occupation distribution.
- **startprob_posterior** (array, shape (n_components,)) - Posterior estimate of the state occupation distribution.
- **transmat_prior** (array, shape (n_components, n_components)) - Prior for the matrix of transition probabilities between states.
- **transmat_posterior** (array, shape (n_components, n_components)) - Posterior estimate of the transition probabilities between states.
- **emissionprob_prior** (array, shape (n_components, n_features)) - Prior estimatate of emitting a given symbol when in each state.
- **emissionprob_posterior** (array, shape (n_components, n_features)) - Posterior estimate of emitting a given symbol when in each state.

### Example
```python
>>> from hmmlearn.hmm import VariationalCategoricalHMM
>>> VariationalCategoricalHMM(n_components=2)  
VariationalCategoricalHMM(algorithm='viterbi',...
```
```

--------------------------------

### Inspect VI and EM models with 6 states and plot Hinton diagrams

Source: https://hmmlearn.readthedocs.io/en/stable/_sources/auto_examples/plot_variational_inference.rst.txt

Inspects the VI and EM models with 6 states, printing their transition matrices, means, and covariances, then generates Hinton diagrams for both solutions and displays them with plt.show().

```python
vi_model = best_models["VI"][6]
    em_model = best_models["EM"][6]
    print("VI solution for 6 states: Notice sparsity among states 1 and 4")
    print(vi_model.transmat_)
    print(vi_model.means_)
    print(vi_model.covars_)
    print("EM solution for 6 states")
    print(em_model.transmat_)
    print(em_model.means_)
    print(em_model.covars_)

    f = gaussian_hinton_diagram(
        vi_model.startprob_,
        vi_model.transmat_,
        vi_model.means_.ravel(),
        vi_model.covars_.ravel(),
    )
    f.suptitle("Variational Inference Solution", size=16)
    f = gaussian_hinton_diagram(
        em_model.startprob_,
        em_model.transmat_,
        em_model.means_.ravel(),
        em_model.covars_.ravel(),
    )
    f.suptitle("Expectation-Maximization Solution", size=16)

    plt.show()
```

--------------------------------

### Output of transition matrix comparison

Source: https://hmmlearn.readthedocs.io/en/stable/_sources/auto_examples/plot_casino.rst.txt

Shows the generated and recovered transition matrices, demonstrating that the recovered matrix closely approximates the true one.

```none
Transmission Matrix Generated:
[[0.95 0.05]
 [0.1  0.9 ]]

Transmission Matrix Recovered:
[[0.922 0.078]
 [0.059 0.941]]
```

--------------------------------

### PoissonHMM fitting output

Source: https://hmmlearn.readthedocs.io/en/stable/auto_examples/plot_poisson_hmm.html

Example output from the PoissonHMM fitting loop. Shows that all 40 fits converged, with scores ranging from about -391.9 to -328.0, and that the best model (score -328.02126544237643) has 4 components.

```text
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -391.9189281654951
Converged: True         Score: -341.8939704987539
Converged: True         Score: -341.8824477272133
Converged: True         Score: -342.1445482378539
Converged: True         Score: -341.89296748597087
Converged: True         Score: -341.8855538199321
Converged: True         Score: -342.2876227612761
Converged: True         Score: -342.5369292103597
Converged: True         Score: -341.88750207762183
Converged: True         Score: -341.8789363379968
Converged: True         Score: -342.97038817436885
Converged: True         Score: -343.04291690398725
Converged: True         Score: -342.0845203955183
Converged: True         Score: -342.68927432019893
Converged: True         Score: -328.59774278053084
Converged: True         Score: -341.6613001106412
Converged: True         Score: -329.06399427715905
Converged: True         Score: -329.5050253557599
Converged: True         Score: -338.9078699324081
Converged: True         Score: -328.75627821896546
Converged: True         Score: -337.651574496105
Converged: True         Score: -328.14045680319686
Converged: True         Score: -340.59777383065585
Converged: True         Score: -330.46705382979616
Converged: True         Score: -341.56334292712467
Converged: True         Score: -328.02126544237643
Converged: True         Score: -340.86474747756444
Converged: True         Score: -339.55978555721873
Converged: True         Score: -328.69847130568803
Converged: True         Score: -328.8760462922789
Converged: True         Score: -340.13188775835437
The best model had a score of -328.02126544237643 and 4 components
```

--------------------------------

### Instantiate GaussianHMM with n_components=2

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Shows how to instantiate a GaussianHMM with two components. The output is truncated in the source, indicated by the ellipsis.

```python
>>> from hmmlearn.hmm import GaussianHMM
>>> GaussianHMM(n_components=2)  
GaussianHMM(algorithm='viterbi',...
```

--------------------------------

### Instantiate VariationalGaussianHMM with n_components=2

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Shows how to instantiate a VariationalGaussianHMM with two components. The output is truncated in the source, indicated by the ellipsis.

```python
>>> from hmmlearn.hmm import VariationalGaussianHMM
>>> VariationalGaussianHMM(n_components=2)  
VariationalGaussianHMM(algorithm='viterbi',...

```

--------------------------------

### Build GaussianHMM and generate samples

Source: https://hmmlearn.readthedocs.io/en/stable/tutorial.html

Build a GaussianHMM with three components and full covariance, set all parameters manually, and generate 100 samples. The random seed is fixed for reproducibility.

```python
>>> import numpy as np
>>> from hmmlearn import hmm
>>> np.random.seed(42)
>>>
>>> model = hmm.GaussianHMM(n_components=3, covariance_type="full")
>>> model.startprob_ = np.array([0.6, 0.3, 0.1])
>>> model.transmat_ = np.array([[0.7, 0.2, 0.1],
...                             [0.3, 0.5, 0.2],
...                             [0.3, 0.3, 0.4]])
>>> model.means_ = np.array([[0.0, 0.0], [3.0, -3.0], [5.0, 10.0]])
>>> model.covars_ = np.tile(np.identity(2), (3, 1, 1))
>>> X, Z = model.sample(100)
```

--------------------------------

### Output of HMM fitting and best model selection

Source: https://hmmlearn.readthedocs.io/en/stable/auto_examples/plot_hmm_sampling_and_decoding.html

Example output from the model fitting loop showing convergence status and scores for each of the 30 fitted models, followed by the best model's score and number of states (5).

```text
Converged: True Score: -1464.4537093530705
Converged: True Score: -1160.0376561677629
Converged: True Score: -1073.9817948298912
Converged: True Score: -1073.9817948298914
Converged: True Score: -1152.6403059684721
Converged: True Score: -1073.9817948298937
Converged: True Score: -1073.9817948298905
Converged: True Score: -1073.9817948298848
Converged: True Score: -1073.9817945857505
Converged: True Score: -1073.9817948298914
Converged: True Score: -904.4104011027309
Converged: True Score: -1079.9023012348102
Converged: True Score: -932.6769411019295
Converged: True Score: -1074.6321161892483
Converged: True Score: -932.2719797716564
Converged: True Score: -1036.3526634658729
Converged: True Score: -968.3080856410083
Converged: True Score: -932.2719797716553
Converged: True Score: -932.2719797716552
Converged: True Score: -931.5620928935114
Converged: True Score: -1046.6202745712717
Converged: True Score: -1011.721789620891
Converged: True Score: -938.4388006572714
Converged: True Score: -945.9969557801252
Converged: True Score: -939.1979464345783
Converged: True Score: -854.4184482162858
Converged: True Score: -944.7507615355137
Converged: True Score: -937.6419960807413
Converged: True Score: -863.8523113387329
Converged: True Score: -824.9904922608579
The best model had a score of -824.9904922608579 and 5 states
```

--------------------------------

### Simulate dishonest casino rolls with CategoricalHMM

Source: https://hmmlearn.readthedocs.io/en/stable/_sources/auto_examples/plot_casino.rst.txt

Creates a CategoricalHMM with two states (fair and loaded die), sets start, transition, and emission probabilities, samples 30,000 rolls, and plots the hidden states and roll distributions by state.

```Python
# make our generative model with two components, a fair die and a
# loaded die
gen_model = hmm.CategoricalHMM(n_components=2, random_state=99)

# the first state is the fair die so let's start there so no one
# catches on right away
gen_model.startprob_ = np.array([1.0, 0.0])

# now let's say that we sneak the loaded die in:
# here, we have a 95% chance to continue using the fair die and a 5%
# chance to switch to the loaded die
# when we enter the loaded die state, we have a 90% chance of staying
# in that state and a 10% chance of leaving
gen_model.transmat_ = np.array([[0.95, 0.05],
                                [0.1, 0.9]])

# now let's set the emission means:
# the first state is a fair die with equal probabilities and the
# second is loaded by being biased toward rolling a six
gen_model.emissionprob_ = \
    np.array([[1 / 6, 1 / 6, 1 / 6, 1 / 6, 1 / 6, 1 / 6],
              [1 / 10, 1 / 10, 1 / 10, 1 / 10, 1 / 10, 1 / 2]])

# simulate the loaded dice rolls
rolls, gen_states = gen_model.sample(30000)

# plot states over time, let's just look at the first rolls for clarity
fig, ax = plt.subplots()
ax.plot(gen_states[:500])
ax.set_title('States over time')
ax.set_xlabel('Time (# of rolls)')
ax.set_ylabel('State')
fig.show()

# plot rolls for the fair and loaded states
fig, ax = plt.subplots()
ax.hist(rolls[gen_states == 0], label='fair', alpha=0.5,
        bins=np.arange(7) - 0.5, density=True)
ax.hist(rolls[gen_states == 1], label='loaded', alpha=0.5,
        bins=np.arange(7) - 0.5, density=True)
ax.set_title('Roll probabilities by state')
ax.set_xlabel('Count')
ax.set_ylabel('Roll')
ax.legend()
fig.show()

```

--------------------------------

### Import and instantiate VariationalCategoricalHMM

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Shows how to import and instantiate a VariationalCategoricalHMM with two components. The output is truncated in the source, indicated by the ellipsis.

```python
>>> from hmmlearn.hmm import VariationalCategoricalHMM
>>> VariationalCategoricalHMM(n_components=2)  
VariationalCategoricalHMM(algorithm='viterbi',...

```

--------------------------------

### sample

Source: https://hmmlearn.readthedocs.io/en/stable/api.html

Generates random samples from the model.

```APIDOC
## sample(n_samples=1, random_state=None, currstate=None)

### Description
Generates random samples from the model.

### Method
Method: sample

### Parameters
- **n_samples** (int) - Number of samples to generate.
- **random_state** (RandomState or an int seed) - A random number generator instance. If `None`, the object's `random_state` is used.
- **currstate** (int) - Current state, as the initial state of the samples.

### Returns
- **X** (array, shape (n_samples, n_features)) - Feature matrix.
- **state_sequence** (array, shape (n_samples,)) - State sequence produced by the model.

### Examples
```
# generate samples continuously
_, Z = model.sample(n_samples=10)
X, Z = model.sample(n_samples=10, currstate=Z[-1])
```
```
Tokens:
Raw