class MaximumLikelihoodHMM

class deeptime.markov.hmm.MaximumLikelihoodHMM(initial_model: HiddenMarkovModel, lagtime: int, stride: Union[int, str] = 1, reversible: bool = True, stationary: bool = False, p: Optional[ndarray] = None, accuracy: float = 0.001, maxit: int = 1000, maxit_reversible: int = 100000)

Maximum likelihood Hidden Markov model (HMM) estimator.

This class is used to fit a maximum-likelihood HMM to data. It uses an initial guess HMM with can be obtained with one of the provided heuristics and then uses the Baum-Welch algorithm [1] to fit the initial guess to provided data.

The type of output model (gaussian or discrete) and the number of hidden states are extracted from the initial model. In case no initial distribution was given, the initial model assumes a uniform initial distribution.

Parameters:

• initial_model (HiddenMarkovModel) – This model will be used to initialize the hidden markov model estimation routine. Since it is prone to get stuck in local optima, several initializations should be tried and scored and/or one of the available initialization heuristics should be applied, if appropriate.

• lagtime (int) –

  Lag parameter used for fitting the HMM.

  Note that this parameter is completely independent from what was used for estimating the initial HMM.

• stride (int or str, optional, default=1) –

  stride between two lagged trajectories extracted from the input trajectories. Given trajectory s[t], stride and lag will result in trajectories

  s[0], s[lag], s[2 lag], ...

  s[stride], s[stride + lag], s[stride + 2 lag], ...

  Setting stride = 1 will result in using all data (useful for maximum likelihood estimator), while a Bayesian estimator requires a longer stride in order to have statistically uncorrelated trajectories. Setting stride = ‘effective’ uses the largest neglected timescale as an fit for the correlation time and sets the stride accordingly.

• reversible (bool, optional, default=True) – If True, a prior that enforces reversible transition matrices (detailed balance) is used; otherwise, a standard non-reversible prior is used.

• stationary (bool, optional, default=False) – If True, the initial distribution of hidden states is self-consistently computed as the stationary distribution of the transition matrix. If False, it will be estimated from the starting states. Only set this to true if you’re sure that the observation trajectories are initiated from a global equilibrium distribution.

• p ((n,) ndarray, optional, default=None) – Initial or fixed stationary distribution. If given and stationary=True, transition matrices will be estimated with the constraint that they have the set parameter as their stationary distribution. If given and stationary=False, the parameter is the fixed initial distribution of hidden states.

• accuracy (float, optional, default=1e-3) – Convergence threshold for EM iteration. When two the likelihood does not increase by more than accuracy, the iteration is stopped successfully.

• maxit (int, optional, default=1000) – Stopping criterion for EM iteration. When this many iterations are performed without reaching the requested accuracy, the iteration is stopped without convergence and a warning is given.

• maxit_reversible (int, optional, default=1000000) – Maximum number of iterations for reversible transition matrix estimation. Only used with reversible=True.

References

[1]

Leonard E Baum and John Alonzo Eagon. An inequality with applications to statistical estimation for probabilistic functions of markov processes and to a model for ecology. Bulletin of the American Mathematical Society, 73(3):360–363, 1967.

Attributes

accuracy	Convergence threshold for EM iteration.
fixed_initial_distribution	Fix the initial distribution to the provided value.
fixed_stationary_distribution	Fix the stationary distribution to the provided value.
has_model	Property reporting whether this estimator contains an estimated model.
initial_model	The initial transition model.
lagtime	The lag time at which transitions are counted.
maxit	Stopping criterion for EM iteration.
maxit_reversible	Maximum number of iterations for reversible transition matrix estimation.
model	Shortcut to fetch_model().
n_hidden_states	The number of hidden states, coincides with the number of hidden states in the initial model.
reversible	Whether the hidden transition model should be estimated so that it is reversible.
stationary	If True, the initial distribution of hidden states is self-consistently computed as the stationary distribution of the transition matrix.
stride	Stride to be applied to the input data.

Methods

fetch_model()	Yields the current HiddenMarkovModel or None if fit() was not called yet.
fit(dtrajs[, initial_model, progress])	Fits a new HMM to data.
fit_fetch(data, **kwargs)	Fits the internal model on data and subsequently fetches it in one call.
get_params([deep])	Get the parameters.
set_params(**params)	Set the parameters of this estimator.

fetch_model() → HiddenMarkovModel

Yields the current HiddenMarkovModel or None if fit() was not called yet.

Returns:

model – The model.

Return type:

HiddenMarkovModel or None

fit(dtrajs, initial_model=None, progress=None, **kwargs)

Fits a new HMM to data.

Parameters:

• dtrajs (array_like or list of array_like) – Timeseries data.

• initial_model (HiddenMarkovModel, optional, default=None) – Override for initial_model.

• **kwargs – Ignored kwargs for scikit-learn compatibility.

Returns:

self – Reference to self.

Return type:

MaximumLikelihoodHMM

fit_fetch(data, **kwargs)

Fits the internal model on data and subsequently fetches it in one call.

Parameters:

• data (array_like) – Data that is used to fit the model.

• **kwargs – Additional arguments to fit().

Returns:

The estimated model.

Return type:

model

get_params(deep=False)

Get the parameters.

Returns:

params – Parameter names mapped to their values.

Return type:

mapping of string to any

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – Estimator instance.

Return type:

object

property accuracy: float

Convergence threshold for EM iteration.

property fixed_initial_distribution: Optional[ndarray]

Fix the initial distribution to the provided value. Only used when stationary is False, otherwise refer to fixed_stationary_distribution.

property fixed_stationary_distribution: Optional[ndarray]

Fix the stationary distribution to the provided value. Only used when stationary is True, otherwise refer to fixed_initial_distribution.

property has_model: bool

Property reporting whether this estimator contains an estimated model. This assumes that the model is initialized with None otherwise.

Type:

bool

property initial_model: HiddenMarkovModel

The initial transition model.

property lagtime: int

The lag time at which transitions are counted.

property maxit: int

Stopping criterion for EM iteration.

property maxit_reversible: int

Maximum number of iterations for reversible transition matrix estimation. Only used with reversible=True.

property model

Shortcut to fetch_model().

property n_hidden_states: int

The number of hidden states, coincides with the number of hidden states in the initial model.

property reversible: bool

Whether the hidden transition model should be estimated so that it is reversible.

property stationary: bool

If True, the initial distribution of hidden states is self-consistently computed as the stationary distribution of the transition matrix. If False, it will be estimated from the starting states. Only set this to true if you’re sure that the observation trajectories are initiated from a global equilibrium distribution.

property stride: Union[int, str]

Stride to be applied to the input data. Must be compatible with how the initial model was estimated.