msmbuilder.hmm.VonMisesHMM¶

class msmbuilder.hmm.VonMisesHMM(n_states=1, transmat=None, transmat_prior=None, reversible_type='mle', random_state=None, n_iter=10, thresh=0.01, params='tmk', init_params='tmk')¶

Hidden Markov Model with von Mises Emissions

The von Mises distribution, (also known as the circular normal distribution or Tikhonov distribution) is a continuous probability distribution on the circle. For multivariate signals, the emmissions distribution implemented by this model is a product of univariate von Mises distributuons – analogous to the multivariate Gaussian distribution with a diagonal covariance matrix.

This class allows for easy evaluation of, sampling from, and maximum-likelihood estimation of the parameters of a HMM.

Parameters:

n_states : int

Number of states in the model.

random_state: RandomState or an int seed (0 by default)

A random number generator instance

n_iter : int, optional

Number of iterations to perform.

thresh : float, optional

Convergence threshold.

params : string, optional

Controls which parameters are updated in the training process. Can contain any combination of ‘t’ for transmat, ‘m’ for means, and ‘k’ for kappas. Defaults to all parameters.

reversible_type : str

Method by which the reversibility of the transition matrix is enforced. ‘mle’ uses a maximum likelihood method that is solved by numerical optimization (BFGS), and ‘transpose’ uses a more restrictive (but less computationally complex) direct symmetrization of the expected number of counts.

init_params : string, optional

Controls which parameters are initialized prior to training. Can contain any combination of ‘t’ for transmat, ‘m’ for means, and ‘k’ for kappas, the concentration parameters. Defaults to all parameters.

Notes

The formulas for the maximization step of the E-M algorithim are adapted from [R25], especially equations (11) and (13).

References

[R25]

(1, 2) Prati, Andrea, Simone Calderara, and Rita Cucchiara. “Using circular

statistics for trajectory shape analysis.” Computer Vision and Pattern Recognition, 2008. CVPR 2008. IEEE Conference on. IEEE, 2008. .. [R26] Murray, Richard F., and Yaniv Morgenstern. “Cue combination on the circle and the sphere.” Journal of vision 10.11 (2010).

Attributes

`transmat_`	Matrix of transition probabilities.
`startprob_`	Mixing startprob for each state.
`means_`	Mean parameters for each state.
`kappas_`	Concentration parameter for each state.

n_features

(int) Dimensionality of the emissions.

Methods

`decode`(obs[, algorithm])	Find most likely state sequence corresponding to `obs`.
`eval`(X)
`fit`(obs)	Estimate model parameters.
`get_params`([deep])	Get parameters for this estimator.
`overlap_`()	Compute the matrix of normalized log overlap integrals between the hidden state distributions
`predict`(obs[, algorithm])	Find most likely state sequence corresponding to obs.
`predict_proba`(obs)	Compute the posterior probability for each state in the model
`sample`([n, random_state])	Generate random samples from the model.
`score`(obs)	Compute the log probability under the model.
`score_samples`(obs)	Compute the log probability under the model and compute posteriors.
`set_params`(**params)	Set the parameters of this estimator.
`summarize`()	Return some diagnostic summary statistics about this Markov model
`timescales_`()	The implied relaxation timescales of the hidden Markov transition

means_¶: Mean parameters for each state.

kappas_¶: Concentration parameter for each state. If kappa is zero, the distriution is uniform. If large, it gets very concentrated about mean

fit(obs)¶

Estimate model parameters.

An initialization step is performed before entering the EM algorithm. If you want to avoid this step, pass proper init_params keyword argument to estimator’s constructor.

Parameters:

obs : list

List of array-like observation sequences, each of which has shape (n_i, n_features), where n_i is the length of the i_th observation.

Notes

In general, logprob should be non-decreasing unless aggressive pruning is used. Decreasing logprob is generally a sign of overfitting (e.g. a covariance parameter getting too small). You can fix this by getting more training data, or strengthening the appropriate subclass-specific regularization parameter.

overlap_()¶

Compute the matrix of normalized log overlap integrals between the hidden state distributions

Returns:

noverlap : array, shape=(n_components, n_components)

noverlap[i,j] gives the log of normalized overlap integral between states i and j. The normalized overlap integral is `integral(f(i)*f(j)) / sqrt[integral(f(i)*f(i)) * integral(f(j)*f(j))]

Notes

The analytic formula used here follows from equation (A4) in 2

timescales_()¶

The implied relaxation timescales of the hidden Markov transition matrix

By diagonalizing the transition matrix, its propagation of an arbitrary initial probability vector can be written as a sum of the eigenvectors of the transition weighted by per-eigenvector term that decays exponentially with time. Each of these eigenvectors describes a “dynamical mode” of the transition matrix and has a characteristic timescale, which gives the timescale on which that mode decays towards equilibrium. These timescales are given by \(-1/log(u_i)\) where \(u_i\) are the eigenvalues of the transition matrix. In an HMM with N components, the number of non-infinite timescales is N-1. (The -1 comes from the fact that the stationary distribution of the chain is associated with an eigenvalue of 1, and an infinite characteritic timescale).

Returns:

timescales : array, shape=[n_states-1]

The characteristic timescales of the transition matrix. If the model has not been fit or does not have a transition matrix, the return value will be None. The timescales are ordered from longest to shortest.

algorithm¶: decoder algorithm

decode(obs, algorithm='viterbi')¶

Find most likely state sequence corresponding to obs. Uses the selected algorithm for decoding.

Parameters:

obs : array_like, shape (n, n_features)

Sequence of n_features-dimensional data points. Each row corresponds to a single point in the sequence.

algorithm : string, one of the decoder_algorithms

decoder algorithm to be used

Returns:

logprob : float

Log probability of the maximum likelihood path through the HMM

state_sequence : array_like, shape (n,)

Index of the most likely states for each observation