### Multinomial HMM Setup and Training

Source: https://hmmlearn.readthedocs.io/en/stable/_downloads/d69b23b6a2a5281e5be109a3f009a071/plot_multinomial_hmm.ipynb

Sets up a Multinomial HMM with predefined start probabilities, transition matrix, and emission probabilities. It then fits the model to sequences of word counts and decodes the most likely hidden states (topics). This snippet requires numpy and hmmlearn. The data is prepared by converting sentences into bag-of-words counts.

```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_)
```

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

### HMM Parameter Setup and Data Generation

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

Sets up parameters for a 4-component Gaussian HMM and generates sample sequences. This is a prerequisite for training and comparing different models.

```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)
```

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

### Initialize VariationalCategoricalHMM

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

Instantiate a VariationalCategoricalHMM with 2 components. This is a basic setup for a discrete HMM.

```python
from hmmlearn.hmm import VariationalCategoricalHMM
VariationalCategoricalHMM(n_components=2)
```

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

### Initialize CategoricalHMM

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

Demonstrates how to initialize a CategoricalHMM model with a specified number of components. This is a basic setup for creating a new HMM instance.

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

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

### Setting up a Multinomial HMM

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

Defines the parameters for a Multinomial HMM, including states, start probabilities, emission probabilities, and transition matrix. This setup is useful for modeling sequences where observations are counts or frequencies across categories.

```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]])
```

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

### sample

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

Generate random samples from the model, optionally starting from a specific state.

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

### Description
Generate random samples from the model.

### 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])
```

```

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

### Multinomial HMM Example (Previous Version)

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

This snippet demonstrates the previous implementation of Multinomial HMM, which was effectively a Categorical HMM. It shows the learned emission probabilities and transition matrix for a given set of topics.

```python
Topics discussed:
['cat', 'cat', 'cat', 'cat', 'cat', 'dog', 'dog', 'cat', 'cat', 'dog', 'cat', 'cat', 'cat', 'cat', 'cat', 'dog', 'dog', 'cat', 'cat', 'dog', 'cat', 'cat', 'cat', 'cat', 'cat', 'dog', 'dog', 'cat', 'cat', 'dog', 'cat', 'cat', 'cat', 'cat', 'cat', 'dog', 'dog', 'cat', 'cat', 'dog', 'cat', 'cat', 'cat', 'cat', 'cat', 'dog', 'dog', 'cat', 'cat', 'dog']
Learned emission probs:
[[2.57129200e-01 2.86190571e-02 4.28541642e-01 2.85710101e-01]
 [1.33352852e-01 7.33292496e-01 2.67548571e-05 1.33327897e-01]]
Learned transition matrix:
[[0.71429762 0.28570238]
 [0.50007593 0.49992407]]
```

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

### Initialize GaussianHMM with Fixed Transition Matrix

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

Builds a GaussianHMM and explicitly sets the transition probability matrix. The `init_params` argument is set to 'mcs' to indicate that means, covariances, and start probabilities will be initialized, but the transition matrix will be set manually.

```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]])

```

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

### Multinomial HMM Example (New Implementation)

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

This snippet demonstrates the new implementation of Multinomial HMM, adhering to the standard definition of the Multinomial distribution. It displays the learned emission probabilities and transition matrix for a different set of topics.

```python
Topics discussed:
['dog', 'dog', 'dog', 'dog', 'dog', 'cat', 'cat', 'dog', 'dog', 'cat', 'dog', 'dog', 'dog', 'dog', 'dog', 'cat', 'cat', 'dog', 'dog', 'cat', 'dog', 'dog', 'dog', 'dog', 'dog', 'cat', 'cat', 'dog', 'dog', 'cat', 'dog', 'dog', 'dog', 'dog', 'dog', 'cat', 'cat', 'dog', 'dog', 'cat', 'dog', 'dog', 'dog', 'dog', 'dog', 'cat', 'cat', 'dog', 'dog', 'cat']
Learned emission probs:
[[1.33371306e-01 7.33254643e-01 4.08077235e-05 1.33333243e-01]
 [2.57125044e-01 2.86139179e-02 4.28548609e-01 2.85712429e-01]]
Learned transition matrix:
[[0.49997644 0.50002356]
 [0.28571124 0.71428876]]
```

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

### Visualize GHMM Solutions with Hinton Diagrams

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

Generates Hinton diagrams to visualize the learned parameters (start probabilities, transition matrices, means, and covariances) of the best Variational Inference and Expectation-Maximization models for 6 states. This visualization helps in understanding the structure and differences between the models.

```python
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()
```

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

### Generate Samples Continuously

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

Generates a sequence of samples from the HMM. The second example shows how to continue sampling from the last state of a previous sequence.

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

```

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

### Define a Sample Data Generation Model

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

Defines a GaussianHMM with 4 components and specific parameters (start probabilities, transition matrix, means, and covariances) to generate sample data. This model serves as the ground truth for the subsequent model selection process.

```Python
model = GaussianHMM(4, init_params="")
model.n_features = 4
model.startprob_ = np.array([1/4., 1/4., 1/4., 1/4.])
model.transmat_ = np.array([[0.3, 0.4, 0.2, 0.1],
                                [0.1, 0.2, 0.3, 0.4],
                                [0.5, 0.2, 0.1, 0.2],
                                [0.25, 0.25, 0.25, 0.25]])
model.means_ = np.array([[-2.5], [0], [2.5], [5.]])
model.covars_ = np.sqrt([[0.25], [0.25], [0.25], [0.25]])

X, _ = model.sample(1000, random_state=rs)
lengths = [X.shape[0]]
```

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

### get_metadata_routing

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

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

```APIDOC
## get_metadata_routing

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

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

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

### Multinomial HMM Example

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

This snippet demonstrates how to use MultinomialHMM to model a conversation. It defines states, vocabulary, start probabilities, emission probabilities, and transition matrix. The observed sentences are converted into word count vectors, and the HMM is trained and used to decode the underlying topics.

```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_)

```

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

### Instantiate GaussianHMM

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

Demonstrates how to create an instance of the GaussianHMM class with a specified number of components.

```python
from hmmlearn.hmm import GaussianHMM
GaussianHMM(n_components=2)
```

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

### Build GaussianHMM and Generate Samples

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

Initializes a GaussianHMM with specified components and covariance type, sets initial probabilities, transition matrix, means, and covariances, then generates sample data and hidden states.

```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)
```

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

### _init()

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

Initializes model parameters before fitting using the provided feature matrix.

```APIDOC
## _init(X, lengths=None)

### Description
Initialize model parameters prior to fitting.

### Parameters
* **X** (array-like, shape (n_samples, n_features)) - Feature matrix of individual samples.
* **lengths** (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) - Metadata routing for `lengths` parameter in `score`.
```

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

### get_metadata_routing

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

Get metadata routing of this object.

```APIDOC
## get_metadata_routing

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

### Returns

**routing** (_MetadataRequest_)
  A `MetadataRequest` encapsulating routing information.
```

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

### Initialize VariationalGaussianHMM

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

Instantiate a VariationalGaussianHMM model with a specified number of components.

```python
from hmmlearn.hmm import VariationalGaussianHMM
VariationalGaussianHMM(n_components=2)
```

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

### VariationalBaseHMM._check

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

Validates the model parameters before fitting. Raises a ValueError if any parameters are invalid, such as start probabilities not summing to 1.

```APIDOC
## VariationalBaseHMM._check

### Description
Validates the model parameters before fitting. Raises a ValueError if any parameters are invalid, such as start probabilities not summing to 1.

### Method
_check

### Endpoint
N/A (Internal method, called during fitting)

### Parameters
None

### Request Example
```python
# This method is typically called internally by the fit method.
# Example of direct call (not recommended for general use):
# model._check()
```

### Response
#### Success Response (200)
No explicit return value, but indicates parameters are valid.

#### Response Example
None

### Error Handling
#### ValueError
- Raised if any of the parameters are invalid, e.g., if `startprob_` do not sum to 1.
```

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

### Validate Model Parameters

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

Validates the model parameters before fitting. Raises a ValueError if any parameters are invalid, such as start probabilities not summing to 1.

```python
_check()
```

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

### Compare Transition Matrices

Source: https://hmmlearn.readthedocs.io/en/stable/_downloads/a9e5d9948f8cfb6effb72c83ace9d59e/plot_casino.ipynb

Prints the generated and recovered transition matrices, rounded to three decimal places, for comparison. This helps assess how well the model learned the state transition probabilities.

```python
print(f'Transmission Matrix Generated:\n{gen_model.transmat_.round(3)}\n\n'
      f'Transmission Matrix Recovered:\n{best_model.transmat_.round(3)}\n\n')
```

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

### Comparing VI and EM Solutions for a Specific Number of States

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

Retrieves and prints the transition matrix, means, and covariances for both the best VI and EM models when configured with 6 states. This allows for a direct comparison of the learned parameters and observation of sparsity in the VI solution.

```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_)
```

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

### Load and Plot Earthquake Data

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

Loads earthquake count data and visualizes it to understand the temporal distribution. Ensure matplotlib is installed for plotting.

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

from scipy.stats import poisson
from hmmlearn import hmm

# earthquake data from http://earthquake.usgs.gov/
earthquakes = np.array([
    13, 14, 8, 10, 16, 26, 32, 27, 18, 32, 36, 24, 22, 23, 22, 18,
    25, 21, 21, 14, 8, 11, 14, 23, 18, 17, 19, 20, 22, 19, 13, 26,
    13, 14, 22, 24, 21, 22, 26, 21, 23, 24, 27, 41, 31, 27, 35, 26,
    28, 36, 39, 21, 17, 22, 17, 19, 15, 34, 10, 15, 22, 18, 15, 20,
    15, 22, 19, 16, 30, 27, 29, 23, 20, 16, 21, 21, 25, 16, 18, 15,
    18, 14, 10, 15, 8, 15, 6, 11, 8, 7, 18, 16, 13, 12, 13, 20,
    15, 16, 12, 18, 15, 16, 13, 15, 16, 11, 11])


# Plot the sampled data
fig, ax = plt.subplots()
ax.plot(earthquakes, ".-", ms=6, mfc="orange", alpha=0.7)
ax.set_xticks(range(0, earthquakes.size, 10))
ax.set_xticklabels(range(1906, 2007, 10))
ax.set_xlabel('Year')
ax.set_ylabel('Count')
fig.show()
```

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

### Define and Configure Sample Data Generator

Source: https://hmmlearn.readthedocs.io/en/stable/_downloads/fd1a3fc6ed977a28f7a319fb523ecc61/plot_gaussian_model_selection.ipynb

Sets up a GaussianHMM model to generate sample data. This includes defining the number of components, features, initial parameters, transition matrix, means, and covariances.

```python
model = GaussianHMM(4, init_params="")
model.n_features = 4
model.startprob_ = np.array([1/4., 1/4., 1/4., 1/4.])
model.transmat_ = np.array([[0.3, 0.4, 0.2, 0.1],
                            [0.1, 0.2, 0.3, 0.4],
                            [0.5, 0.2, 0.1, 0.2],
                            [0.25, 0.25, 0.25, 0.25]])
model.means_ = np.array([[-2.5], [0], [2.5], [5.]])
model.covars_ = np.sqrt([[0.25], [0.25], [0.25], [0.25]])

X, _ = model.sample(1000, random_state=rs)
lengths = [X.shape[0]]
```

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

### Build Left-Right GaussianHMM

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

Constructs a left-right GaussianHMM, specifying initialization and estimation parameters, and setting the start probability and transition matrix to enforce a left-to-right state progression.

```python
lr = hmm.GaussianHMM(n_components=3, covariance_type="diag",
                     init_params="cm", params="cmt")
lr.startprob_ = np.array([1.0, 0.0, 0.0])
lr.transmat_ = np.array([[0.5, 0.5, 0.0],
                         [0.0, 0.5, 0.5],
                         [0.0, 0.0, 1.0]])
```

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

### sample

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

Generate random samples from the model.

```APIDOC
## sample

Generate random samples from the model.

### 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_, _1_)_)
  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])
```
```

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

### set_fit_request

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

Request metadata passed to the `fit` method. Note that this method is only relevant if `enable_metadata_routing=True` (see `sklearn.set_config()`). Please see User Guide on how the routing mechanism works.

```APIDOC
## set_fit_request

### Description
Request metadata passed to the `fit` method. Note that this method is only relevant if `enable_metadata_routing=True` (see `sklearn.set_config()`). Please see User Guide on how the routing mechanism works.
The options for each parameter are:
  * `True`: metadata is requested, and passed to `fit` if provided. The request is ignored if metadata is not provided.
  * `False`: metadata is not requested and the meta-estimator will not pass it to `fit`.
  * `None`: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
  * `str`: metadata should be passed to the meta-estimator with this given alias instead of the original name.

### Returns
**self** (VariationalGaussianHMM) - Returns self.
```

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

### sample

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

Generate random samples from the model.

```APIDOC
## sample

### Description
Generate random samples from the model.

### Parameters
#### Path 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])
```
```

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

### VariationalBaseHMM#_compute_lower_bound

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

Computes the Variational Lower Bound of the model. Derived implementations should call this method to get the contribution of the current log_prob, transmat, and startprob towards the lower bound.

```APIDOC
## _compute_lower_bound(_curr_logprob_)

### Description
Compute the Variational Lower Bound of the model as currently configured. Following the pattern elsewhere, derived implementations should call this method to get the contribution of the current log_prob, transmat, and startprob towards the lower bound.

### Parameters
* **curr_logprob** (_float_) – The current log probability of the data as computed at the subnormalized model parameters.

### Returns
* **lower_bound** (_float_) – Returns the computed lower bound contribution of the log_prob, startprob, and transmat.
```

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

### sample

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

Generate random samples from the Hidden Markov Model.

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

### Description
Generate random samples from the model.

### Parameters
#### 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])
```
```

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

### Generate Samples with VariationalCategoricalHMM

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

Generates random samples from the HMM model. The first call generates 10 samples, and the second call generates another 10 samples starting from the last state of the previous sequence.

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

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

### Generate a dishonest casino model and simulate rolls

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

Creates a generative HMM with two states (fair and loaded die), sets their start probabilities, transition probabilities, and emission probabilities. It then simulates a sequence of 30,000 rolls.

```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)

```

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

### Generating Training Data for HMM

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

This snippet sets up a 4-component Gaussian HMM and generates synthetic sequences for training. It defines the initial probabilities, transition matrix, means, and covariances of the model.

```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)

```

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

### Visualize Gaussian HMM Parameters

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

Helper function to visualize initial probabilities, transition probabilities, and emission distributions of a Gaussian HMM. Useful for understanding the learned model structure.

```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

```

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

### Generate Samples from a Gaussian HMM

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

Define parameters for a 4-component Gaussian HMM, including start probabilities, transition matrix, means, and covariances. Then, generate synthetic observations (X) and their corresponding hidden states (Z) using the defined model.

```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()
```

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

### Visualize HMM Parameters with Gaussian Hinton Diagram

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

This function visualizes the initial state probabilities, transition probabilities, and emission distributions for a Hidden Markov Model with Gaussian emissions. It's useful for understanding the learned parameters of the model.

```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:

```

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

### _initialize_sufficient_statistics

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

Initialize sufficient statistics required for the M-step of the EM algorithm. Returns statistics in a dictionary.

```APIDOC
## _initialize_sufficient_statistics

### Description
Initialize sufficient statistics required for M-step. The method is _pure_ , meaning that it doesn’t change the state of the instance. For extensibility computed statistics are stored in a dictionary.

### Returns
* **nobs** (_int_) – Number of samples in the data.
* **start** (_array, shape (n_components, )_) – An array where the i-th element corresponds to the posterior probability of the first sample being generated by the i-th state.
* **trans** (_array, shape (n_components, n_components)_) – An array where the (i, j)-th element corresponds to the posterior probability of transitioning between the i-th to j-th states.
```

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

### sample

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

Generates random samples and their corresponding hidden state sequences from the trained model.

```APIDOC
## sample

### Description
Generate random samples from the model.

### 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])
```
```

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

### Plotting Variational Inference and EM Solutions

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

This snippet visualizes the results of Variational Inference and Expectation-Maximization for a Gaussian HMM. It uses the `gaussian_hinton_diagram` function to plot the start probabilities, transition matrices, means, and covariances for both methods. Ensure `matplotlib.pyplot` is imported as `plt` and the necessary models (`vi_model`, `em_model`) are defined.

```python
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()
```