**hmm**¶

Baum-Welch filter/smoother for hidden Markov models.

## Overview¶

A hidden Markov model (HMM) is a state-space model with a finite state-space, {1, …, K}. The Baum-Welch algorithm allows to compute (exactly) the filtering and smoothing distributions of such a model; i.e. the probabilities that X_t=k given data Y_{0:t} (filtering) or the complete data Y_{0:T} (smoothing). In addition, one may sample trajectories from the complete smoothing distribution (the distribution of all the states, X_{0:T}, given all the data).

Hidden Markov models and the Baum-Welch algorithm are covered in Chapter 6 of the book.

## Running the Baum-Welch algorithm¶

Class `BaumWelch`

is instantiated as follows:

```
bw = BaumWelch(hmm=my_hmm, data=y)
```

To actually run the algorithm, one must invoke the appropriate methods, e.g.:

```
bw.forward() # computes the filtering probs
bw.backward() # computes the marginal smoothing probs
bw.sample(N=30) # generate 30 smoothing trajectories
```

If you invoke either `backward`

or `sample`

directly, the forward pass will be
run first. The output of the forward and backward passes are attributes of
object `bw`

, which are lists of K-length numpy arrays. For instance,
`self.filt`

is a list of arrays containing the filtering probabilities; see the
documentation of `BaumWelch`

for more details.

## Running the forward pass step by step¶

A `BaumWelch`

object is an iterator; each iteration performs a single step of
the forward pass. It is thus possible for the user to run the forward pass step
by step:

```
next(bw) # performs one step of the forward pass
```

This may be useful in a variety of scenarios, such as when data are acquired on
the fly (in that case, modify attribute `self.data`

directly), or when one
wants to perform the smoothing pass at different times; in particular:

```
bw = BaumWelch(hmm=mh_hmm, data=y)
for t, _ in enumerate(y):
bw.step()
bw.backward()
## save the results in bw.smth somewhere
```

would compute all the intermediate smoothing distributions (for data $Y_0$, then $Y_{0:1}$, and so on). This is expensive, of course (cost is O(T^2)).

## Module summary¶

`HMM` |
Base class for hidden Markov models. |

`GaussianHMM` |
Gaussian HMM: \(Y_t|X_t=k \sim N(\mu_k, \sigma_k^2)\) |

`BaumWelch` |
Baum-Welch filtering/smoothing algorithm. |