pyemma.msm.SampledHMSM¶

class pyemma.msm.SampledHMSM(samples, ref=None, conf=0.95)¶

Sampled Hidden Markov state model

__init__(samples, ref=None, conf=0.95)¶

Constructs a sampled HMSM

Parameters:	samples (list of HMSM) – Sampled HMSM objects ref (HMSM) – Single-point estimator, e.g. containing a maximum likelihood HMSM. If not given, the sample mean will be used. conf (float, optional, default=0.95) – Confidence interval. By default two-sigma (95.4%) is used. Use 95.4% for two sigma or 99.7% for three sigma.

Methods

__init__(samples[, ref, conf]) Constructs a sampled HMSM

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])

sample_conf(f, *args, **kwargs) Sample confidence interval of numerical method f over all samples

sample_f(f, *args, **kwargs) Evaluated method f for all samples

sample_mean(f, *args, **kwargs) Sample mean of numerical method f over all samples

sample_std(f, *args, **kwargs) Sample standard deviation of numerical method f over all samples

set_model_params([samples, conf, P, pobs, ...])

param samples:	sampled MSMs

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)

sample_conf(f, *args, **kwargs)¶

Sample confidence interval of numerical method f over all samples

Calls f(*args, **kwargs) on all samples and computes the confidence interval. Size of confidence interval is given in the construction of the SampledModel. f must return a numerical value or an ndarray.

Parameters:

f (method reference or name (str)) – Model method to be evaluated for each model sample
args (arguments) – Non-keyword arguments to be passed to the method in each call
kwargs (keyword-argments) – Keyword arguments to be passed to the method in each call

Returns:

L (float or ndarray) – lower value or array of confidence interval
R (float or ndarray) – upper value or array of confidence interval

sample_f(f, *args, **kwargs)¶

Evaluated method f for all samples

Calls f(*args, **kwargs) on all samples.

Parameters:	f (method reference or name (str)) – Model method to be evaluated for each model sample args (arguments) – Non-keyword arguments to be passed to the method in each call kwargs (keyword-argments) – Keyword arguments to be passed to the method in each call
Returns:	vals – list of results of the method calls
Return type:	list

sample_mean(f, *args, **kwargs)¶

Sample mean of numerical method f over all samples

Calls f(*args, **kwargs) on all samples and computes the mean. f must return a numerical value or an ndarray.

Parameters:	f (method reference or name (str)) – Model method to be evaluated for each model sample args (arguments) – Non-keyword arguments to be passed to the method in each call kwargs (keyword-argments) – Keyword arguments to be passed to the method in each call
Returns:	mean – mean value or mean array
Return type:	float or ndarray

sample_std(f, *args, **kwargs)¶

Sample standard deviation of numerical method f over all samples

Calls f(*args, **kwargs) on all samples and computes the standard deviation. f must return a numerical value or an ndarray.

Parameters:	f (method reference or name (str)) – Model method to be evaluated for each model sample args (arguments) – Non-keyword arguments to be passed to the method in each call kwargs (keyword-argments) – Keyword arguments to be passed to the method in each call
Returns:	std – standard deviation or array of standard deviations
Return type:	float or ndarray

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

Parameters:	samples (list of MSM objects) – sampled MSMs conf (float, optional, default=0.68) – Confidence interval. By default one-sigma (68.3%) is used. Use 95.4% for two sigma or 99.7% for three sigma.

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