# Welcome to hmmkay’s documentation!¶

Hmmkay is a basic library for discrete Hidden Markov Models that relies on numba’s just-in-time compilation. It supports decoding, likelihood scoring, fitting (parameter estimation), and sampling.

Hmmkay accepts sequences of arbitrary length, e.g. 2d numpy arrays or lists of iterables. Hmmkay internally converts lists of iterables into Numba typed lists of numpy arrays (you might want to do that yourself to avoid repeated convertions using `hmmkay.utils.check_sequences()`)

Scoring and decoding example:

```>>> from hmmkay.utils import make_proba_matrices
>>> from hmmkay import HMM

>>> init_probas, transition_probas, emission_probas = make_proba_matrices(
...     n_hidden_states=2,
...     n_observable_states=4,
...     random_state=0
... )
>>> hmm = HMM(init_probas, transition_probas, emission_probas)

>>> sequences = [[0, 1, 2, 3], [0, 2]]
>>> hmm.log_likelihood(sequences)
-8.336
>>> hmm.decode(sequences)  # most likely sequences of hidden states
[array([1, 0, 0, 1], dtype=int32), array([1, 0], dtype=int32)]
```

Fitting example:

```>>> from hmmkay.utils import make_observation_sequences
>>> sequences = make_observation_sequences(n_seq=100, n_observable_states=4, random_state=0)
>>> hmm.fit(sequences)
```

Sampling example:

```>>> hmm.sample(n_obs=2, n_seq=3)  # return sequences of hidden and observable states
(array([[0, 1],
[1, 1],
[0, 0]]), array([[0, 2],
[2, 3],
[0, 0]]))
```

# API Reference¶

## HMM class¶

class `hmmkay.``HMM`(init_probas, transitions, emissions, n_iter=10)[source]

Discrete Hidden Markov Model.

The number of hidden and observable states are determined by the shapes of the probability matrices passed as parameters.

Parameters: init_probas (array-like of shape (n_hidden_states,)) – The initial probabilities. transitions (array-like of shape (n_hidden_states, n_hidden_states)) – The transition probabilities. `transitions[i, j] = P(st+1 = j / st = i)`. emissions (array-like of shape (n_hidden_states, n_observable_states)) – The probabilities of symbol emission. ```emissions[i, o] = P(Ot = o / st = i)```. n_iter (int, default=10) – Number of iterations to run for the EM algorithm (in `fit()`).
`decode`(sequences, return_log_probas=False)[source]

Decode sequences with Viterbi algorithm.

Given a sequence of observable states, return the sequence of hidden states that most-likely generated the input.

Parameters: sequences (array-like of shape (n_seq, n_obs) or list (or numba typed list) of iterables of variable length) – The sequences of observable states return_log_probas (bool, default=False) – If True, log-probabilities of the joint sequences of observable and hidden states are returned best_paths (ndarray of shape (n_seq, n_obs) or list of ndarray of variable length) – The most likely sequences of hidden states. log_probabilities (ndarray of shape (n_seq,)) – log-probabilities of the joint sequences of observable and hidden states. Only present if `return_log_probas` is True.
`fit`(sequences)[source]

Fit model to sequences.

The probabilities matrices `init_probas`, `transitions` and `emissions` are estimated with the EM algorithm.

Parameters: sequences (array-like of shape (n_seq, n_obs) or list (or numba typed list) of iterables of variable length) – The sequences of observable states self HMM instance
`log_likelihood`(sequences)[source]

Compute log-likelihood of sequences.

Parameters: sequences (array-like of shape (n_seq, n_obs) or list (or numba typed list) of iterables of variable length) – The sequences of observable states log_likelihood array of shape (n_seq,)
`sample`(n_seq=10, n_obs=10, random_state=None)[source]

Sample sequences of hidden and observable states.

Parameters: n_seq (int, default=10) – Number of sequences to sample n_obs (int, default=10) – Number of observations per sequence random_state (int or np.random.RandomState instance, default=None) – Controls the RNG, see scikt-learn glossary for details. hidden_states_sequences (ndarray of shape (n_seq, n_obs)) observable_states_sequences (ndarray of shape (n_seq, n_obs))

## Utils¶

The utils module contains helpers for input checking, parameter generation and sequence generation.

`hmmkay.utils.``make_observation_sequences`(n_seq=10, n_observable_states=3, n_obs_min=10, n_obs_max=None, random_state=None)[source]

Generate random observation sequences.

Parameters: n_seq (int, default=10) – Number of sequences to generate n_observable_states (int, default=3) – Number of observable states. n_obs_min (int, default=10) – Minimum length of each sequence. n_obs_max (int or None, default=None) – If None (default), all sequences are of length `n_obs_min` and a 2d ndarray is returned. If an int, the length of each sequence is chosen randomly with `n_obs_min <= length < n_obs_max`. A numba typed list of arrays is returned in this case. random_state (int or np.random.RandomState instance, default=None) – Controls the RNG, see scikt-learn glossary for details. sequences – The generated sequences of observable states ndarray of shape (n_seq, n_obs_min,) or numba typed list of ndarray of variable length
`hmmkay.utils.``make_proba_matrices`(n_hidden_states=4, n_observable_states=3, random_state=None)[source]

Generate random probability matrices.

Parameters: n_hidden_states (int, default=4) – Number of hidden states n_observable_states (int, default=3) – Number of observable states random_state (int or np.random.RandomState instance, default=None) – Controls the RNG, see scikt-learn glossary for details. init_probas (array-like of shape (n_hidden_states,)) – The initial probabilities. transitions (array-like of shape (n_hidden_states, n_hidden_states)) – The transition probabilities. `transitions[i, j] = P(st+1 = j / st = i)`. emissions (array-like of shape (n_hidden_states, n_observable_states)) – The probabilities of symbol emission. ```emissions[i, o] = P(Ot = o / st = i)```.
`hmmkay.utils.``check_sequences`(sequences, return_longest_length=False)[source]

Convert sequences into appropriate format.

This helper is called before any method that uses sequences. It is recommended to convert your sequences once and for all before using the `HMM` class, to avoid repeated convertions.

Parameters: sequences (array-like of shape (n_seq, n_obs) or list/typed list of iterables of variable length.) – Lists of iterables are converted to typed lists of numpy arrays, which can have different lengths. 2D arrays are untouched (all sequences have the same length). return_longest_length (bool, default=False) – If True, also return the length of the longest sequence. sequences – The sequences converted either to ndarray or numba typed list of ndarrays. ndarray of shape (n_seq, n_obs) or typed list of ndarray of variable length