pyemma.msm.HMSM¶

class pyemma.msm.HMSM(P, pobs, pi=None, dt_model='1 step')¶

Hidden Markov model on discrete states.

Parameters:	hmm (`DiscreteHMM`) – Hidden Markov Model

__init__(P, pobs, pi=None, dt_model='1 step')¶

Parameters:	Pcoarse (ndarray (m,m)) – coarse-grained or hidden transition matrix Pobs (ndarray (m,n)) – observation probability matrix from hidden to observable discrete states dt_model (str, optional, default='1 step') – time step of the model

Methods

__init__(P, pobs[, pi, dt_model])

param Pcoarse:	coarse-grained or hidden transition matrix

committor_backward(A, B) Backward committor from set A to set B

committor_forward(A, B) Forward committor (also known as p_fold or splitting probability) from set A to set B

correlation(a[, b, maxtime, k, ncv])

eigenvalues([k]) Compute the transition matrix eigenvalues

eigenvectors_left([k]) Compute the left transition matrix eigenvectors

eigenvectors_right([k]) Compute the right transition matrix eigenvectors

expectation(a)

fingerprint_correlation(a[, b, k, ncv])

fingerprint_relaxation(p0, a[, k, ncv])

get_model_params([deep]) Get parameters for this model.

mfpt(A, B) Mean first passage times from set A to set B, in units of the input trajectory time step

pcca(m)

propagate(p0, k) Propagates the initial distribution p0 k times

relaxation(p0, a[, maxtime, k, ncv])

set_model_params([P, pobs, pi, reversible, ...])

param P:	coarse-grained or hidden transition matrix

submodel([states, obs]) Returns a HMM with restricted state space

timescales([k]) The relaxation timescales corresponding to the eigenvalues

transition_matrix_obs([k]) Computes the transition matrix between observed states

update_model_params(**params) Update given model parameter if they are set to specific values

Attributes

`eigenvectors_left_obs`
`eigenvectors_right_obs`
`is_reversible`	Returns whether the MSM is reversible
`is_sparse`	Returns whether the MSM is sparse
`lifetimes`	Lifetimes of states of the hidden transition matrix
`metastable_assignments`	Computes the assignment to metastable sets for observable states
`metastable_distributions`	Returns the output probability distributions.
`metastable_memberships`	Computes the memberships of observable states to metastable sets by Bayesian inversion as described in [1].
`metastable_sets`	Computes the metastable sets of observable states within each
`nstates`	Number of active states on which all computations and estimations are done
`nstates_obs`
`observation_probabilities`	returns the output probability matrix
`stationary_distribution`	The stationary distribution on the MSM states
`stationary_distribution_obs`
`timestep_model`	Physical time corresponding to one transition matrix step, e.g.
`transition_matrix`	The transition matrix on the active set.

committor_backward(A, B)¶

Backward committor from set A to set B

Parameters:	A (int or int array) – set of starting states B (int or int array) – set of target states

committor_forward(A, B)¶

Forward committor (also known as p_fold or splitting probability) from set A to set B

Parameters:	A (int or int array) – set of starting states B (int or int array) – set of target states

eigenvalues(k=None)¶

Compute the transition matrix eigenvalues

Parameters:	k (int) – number of eigenvalues to be returned. By default will return all available eigenvalues
Returns:	ts – transition matrix eigenvalues \(\lambda_i, i = 1, ..., k\)., sorted by descending norm.
Return type:	ndarray(k,)

eigenvectors_left(k=None)¶

Compute the left transition matrix eigenvectors

Parameters:	k (int) – number of eigenvectors to be returned. By default all available eigenvectors.
Returns:	L – left eigenvectors in a row matrix. l_ij is the j’th component of the i’th left eigenvector
Return type:	ndarray(k,n)

eigenvectors_right(k=None)¶

Compute the right transition matrix eigenvectors

Parameters:	k (int) – number of eigenvectors to be computed. By default all available eigenvectors.
Returns:	R – right eigenvectors in a column matrix. r_ij is the i’th component of the j’th right eigenvector
Return type:	ndarray(n,k)

get_model_params(deep=True)¶

Get parameters for this model.

Parameters:	deep (boolean, optional) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns:	params – Parameter names mapped to their values.
Return type:	mapping of string to any

is_reversible¶: Returns whether the MSM is reversible

is_sparse¶: Returns whether the MSM is sparse

lifetimes¶

Lifetimes of states of the hidden transition matrix

Returns:	l – state lifetimes in units of the input trajectory time step, defined by \(-\tau / ln \mid p_{ii} \mid, i = 1,...,nstates\), where \(p_{ii}\) are the diagonal entries of the hidden transition matrix.
Return type:	ndarray(nstates)

metastable_assignments¶

Computes the assignment to metastable sets for observable states

Notes

This is only recommended for visualization purposes. You cannot compute any actual quantity of the coarse-grained kinetics without employing the fuzzy memberships!

Returns:	For each observable state, the metastable state it is located in.
Return type:	ndarray((n) ,dtype=int)

metastable_distributions¶

Returns the output probability distributions. Identical to: observation_probabilities()

Returns:	Pout – output probability matrix from hidden to observable discrete states
Return type:	ndarray (m,n)

See also

observation_probabilities

metastable_memberships¶

Computes the memberships of observable states to metastable sets by: Bayesian inversion as described in [1].

Returns:	M – A matrix containing the probability or membership of each observable state to be assigned to each metastable or hidden state. The row sums of M are 1.
Return type:	ndarray((n,m))

References

[1]	(1, 2) F. Noe, H. Wu, J.-H. Prinz and N. Plattner: Projected and hidden Markov models for calculating kinetics and metastable states of complex molecules. J. Chem. Phys. 139, 184114 (2013)

metastable_sets¶

Computes the metastable sets of observable states within each: metastable set

Notes

This is only recommended for visualization purposes. You cannot compute any actual quantity of the coarse-grained kinetics without employing the fuzzy memberships!

Returns:	sets – A list of length equal to metastable states. Each element is an array with observable state indexes contained in it
Return type:	list of int-arrays

mfpt(A, B)¶

Mean first passage times from set A to set B, in units of the input trajectory time step

Parameters:	A (int or int array) – set of starting states B (int or int array) – set of target states

nstates¶: Number of active states on which all computations and estimations are done

observation_probabilities¶

returns the output probability matrix

Returns:	Pout – output probability matrix from hidden to observable discrete states
Return type:	ndarray (m,n)

propagate(p0, k)¶

Propagates the initial distribution p0 k times

Computes the product

..1: p_k = p_0^T P^k

If the lag time of transition matrix \(P\) is \(\tau\), this will provide the probability distribution at time \(k \tau\).

Parameters:	p0 (ndarray(n)) – Initial distribution. Vector of size of the active set. k (int) – Number of time steps
Returns:	pk – Distribution after k steps. Vector of size of the active set.
Return type:	ndarray(n)

set_model_params(P=None, pobs=None, pi=None, reversible=None, dt_model='1 step', neig=None)¶

Parameters:

P (ndarray(m,m)) – coarse-grained or hidden transition matrix
pobs (ndarray (m,n)) – observation probability matrix from hidden to observable discrete states
pi (ndarray(m), optional, default=None) – stationary or distribution. Can be optionally given in case if it was already computed, e.g. by the estimator.
dt_model (str, optional, default='1 step') – time step of the model
neig (int or None) – The number of eigenvalues / eigenvectors to be kept. If set to None, all eigenvalues will be used.

stationary_distribution¶: The stationary distribution on the MSM states

submodel(states=None, obs=None)¶

Returns a HMM with restricted state space

Parameters:	states (None or int-array) – Hidden states to restrict the model to (if not None). obs (None, str or int-array) – Observed states to restrict the model to (if not None).
Returns:	hmm – The restricted HMM.
Return type:	HMM

timescales(k=None)¶

The relaxation timescales corresponding to the eigenvalues

Parameters:	k (int) – number of timescales to be returned. By default all available eigenvalues, minus 1.
Returns:	ts – relaxation timescales in units of the input trajectory time step, defined by \(-\tau / ln \| \lambda_i \|, i = 2,...,k+1\).
Return type:	ndarray(m)

timestep_model¶: Physical time corresponding to one transition matrix step, e.g. ‘10 ps’

transition_matrix¶: The transition matrix on the active set.

transition_matrix_obs(k=1)¶

Computes the transition matrix between observed states

Transition matrices for longer lag times than the one used to parametrize this HMSM can be obtained by setting the k option. Note that a HMSM is not Markovian, thus we cannot compute transition matrices at longer lag times using the Chapman-Kolmogorow equality. I.e.:

\[P (k \tau) \neq P^k (\tau)\]

This function computes the correct transition matrix using the metastable (coarse) transition matrix \(P_c\) as:

\[P (k \tau) = {\Pi}^-1 \chi^{\top} ({\Pi}_c) P_c^k (\tau) \chi\]

where \(\chi\) is the output probability matrix, \(\Pi_c\) is a diagonal matrix with the metastable-state (coarse) stationary distribution and \(\Pi\) is a diagonal matrix with the observable-state stationary distribution.

Parameters:	k (int, optional, default=1) – Multiple of the lag time for which the By default (k=1), the transition matrix at the lag time used to construct this HMSM will be returned. If a higher power is given,

update_model_params(**params)¶: Update given model parameter if they are set to specific values