class TRAMModel

class deeptime.markov.msm.TRAMModel(count_models, transition_matrices, biased_conf_energies, lagrangian_mult_log, modified_state_counts_log, therm_state_energies=None, markov_state_energies=None)

The TRAM model containing the estimated parameters, free energies, and the underlying Markov models for each thermodynamic state. The TRAM Model is the result of a TRAM estimation and can be used to calculate observables and recover an (unbiased) potential of mean force (PMF). TRAM is described in [1].

Parameters:

• count_models (list(TransitionCountModel)) – The transition count models for all thermodynamic states.

• transition_matrices (ndarray(n, m, m), float64) – The estimated transition matrices for each thermodynamic state. The transition matrices and count models are combined into a MarkovStateModelCollection that holds the Markov models for each thermodynamic state.

• biased_conf_energies (ndarray(n, m), float64) – The estimated free energies \(f_i^k\) of each Markov state for all thermodynamic states. biased_conf_energies[k,i] contains the bias energy of Markov state \(i\) in thermodynamic state \(k\).

• lagrangian_mult_log (ndarray(n, m), float64) – The estimated logarithm of the lagrange multipliers \(v_i^k\) of each Markov state for all thermodynamic states. lagrangian_mult_log[k,i] contains the lagrange multiplier of Markov state \(i\) in thermodynamic state \(k\).

• modified_state_counts_log (ndarray(n, m), float64) – The logarithm of the modified state counts \(R_i^k\) of each Markov state for all thermodynamic states. modified_state_counts_log[k,i] contains the state counts of Markov state \(i\) in thermodynamic state \(k\).

• therm_state_energies (ndarray(n), float64) – The estimated free energy of each thermodynamic state, \(f^k\).

• markov_state_energies (ndarray(m), float64) – The estimated free energy of each Markov state, \(f_i\).

See also

MarkovStateModelCollection, TRAM, TRAMDataset

References

[1] (1,2)

Hao Wu, Fabian Paul, Christoph Wehmeyer, and Frank Noé. Multiensemble markov models of molecular thermodynamics and kinetics. Proceedings of the National Academy of Sciences, 113(23):E3221–E3230, 2016.

Attributes

biased_conf_energies	The estimated free energy per thermodynamic state and Markov state, \(f_k^i\), where \(k\) is the thermodynamic state index, and \(i\) the Markov state index.
lagrangian_mult_log	The estimated logarithm of the lagrange multipliers \(v_i^k\) of each Markov state for all thermodynamic states.
markov_state_energies	The estimated free energy per Markov state, \(f^i\), where \(i\) is the Markov state index.
modified_state_counts_log	The logarithm of the modified state counts \(R_i^k\) of each Markov state for all thermodynamic states.
msm_collection	The underlying MarkovStateModelCollection.
therm_state_energies	The estimated free energy per thermodynamic state, \(f_k\), where \(k\) is the thermodynamic state index.

Methods

compute_PMF(dtrajs, bias_matrices, bin_indices)	Compute the potential of mean force over a number of bins.
compute_log_likelihood(dtrajs, bias_matrices)	The (parameter-dependent part of the) likelihood to observe the given data.
compute_observable(observable_values, ...[, ...])	Compute an observable value.
compute_sample_weights_log(dtrajs, bias_matrices)	Compute the log of the sample weight \(\mathrm{log}\;\mu(x)\) for all samples \(x\).
copy()	Makes a deep copy of this model.
get_params([deep])	Get the parameters.
set_params(**params)	Set the parameters of this estimator.

compute_PMF(dtrajs, bias_matrices, bin_indices, n_bins=None, therm_state=-1)

Compute the potential of mean force over a number of bins.

Parameters:

• dtrajs (list(np.ndarray)) – The list of discrete trajectories. dtrajs[i][n] contains the Markov state index of the \(n\)-th sample in the \(i\)-th trajectory.

• bias_matrices (list(np.ndarray)) – The bias energy matrices. bias_matrices[i][n, k] contains the bias energy of the \(n\)-th sample from the \(i\)-th trajectory, evaluated at thermodynamic state \(k\), \(b^k(x_{i,n})\). The bias energy matrices should have the same size as dtrajs in both the first and second dimension. The third dimension is of size n_therm_state, i.e. for each sample, the bias energy in every thermodynamic state is calculated and stored in the bias_matrices.

• bin_indices (list(np.ndarray)) – The list of bin indices that the samples are binned into. The PMF is calculated as a distribution over these bins. binned_samples[i][n] contains the bin index for the \(n\)-th sample in the \(i\)-th trajectory.

• n_bins (int, optional) – The number of bins. If None, n_bins is inferred from the maximum bin index. The PMF array

• therm_state (int, optional, default=-1) – The index of the thermodynamic state in which the PMF need to be computed. If therm_state=-1, the PMF is computed for the unbiased (reference) state.

Returns:

PMF – A ndarray of size n_bins containing the estimated PMF from the data. Is n_bins was None, the PMF is of size max(bin_indices) + 1.

Return type:

np.ndarray

compute_log_likelihood(dtrajs, bias_matrices)

The (parameter-dependent part of the) likelihood to observe the given data.

The definition can be found in [1], Equation (9).

Parameters:

• dtrajs (list(np.ndarray)) – The list of discrete trajectories. dtrajs[i][n] contains the Markov state index of the \(n\)-th sample in the \(i\)-th trajectory.

• bias_matrices (list(np.ndarray)) – The bias energy matrices. bias_matrices[i][n, k] contains the bias energy of the \(n\)-th sample from the \(i\)-th trajectory, evaluated at thermodynamic state \(k\), \(b^k(x_{i,n})\). The bias energy matrices should have the same size as dtrajs in both the first and second dimension. The third dimension is of size n_therm_state, i.e. for each sample, the bias energy in every thermodynamic state is calculated and stored in the bias_matrices.

Returns:

log_likelihood – The parameter-dependent part of the log-likelihood.

Return type:

float

Notes

Parameter-dependent, i.e., the factor

\[\prod_{x \in X} e^{-b^{k(x)}(x)} \]

does not occur in the log-likelihood as it is constant with respect to the parameters, leading to

\[\log \prod_{k=1}^K \left(\prod_{i,j} (p_{ij}^k)^{c_{ij}^k}\right) \left(\prod_{i} \prod_{x \in X_i^k} \mu(x) e^{f_i^k} \right) \]

compute_observable(observable_values, dtrajs, bias_matrices, therm_state=-1)

Compute an observable value.

Parameters:

• observable_values (list(np.ndarray)) – The list of observable values. observable_values[i][n] contains the observable value for the \(n\)-th sample in the \(i\)-th trajectory.

• dtrajs (list(np.ndarray)) – The list of discrete trajectories. dtrajs[i][n] contains the Markov state index of the \(n\)-th sample in the \(i\)-th trajectory.

• bias_matrices (list(np.ndarray)) – The bias energy matrices. bias_matrices[i][n, k] contains the bias energy of the \(n\)-th sample from the \(i\)-th trajectory, evaluated at thermodynamic state \(k\), \(b^k(x_{i,n})\). The bias energy matrices should have the same size as dtrajs in both the first and second dimension. The third dimension is of size n_therm_state, i.e. for each sample, the bias energy in every thermodynamic state is calculated and stored in the bias_matrices.

• therm_state (int, optional, default=-1) – The index of the thermodynamic state in which the observable need to be computed. If therm_state=-1, the observable is computed for the unbiased (reference) state.

Returns:

observable – The expected value of the observable in the selected thermodynamic state therm_state.

Return type:

float

compute_sample_weights_log(dtrajs, bias_matrices, therm_state=-1)

Compute the log of the sample weight \(\mathrm{log}\;\mu(x)\) for all samples \(x\). If the thermodynamic state index is >= 0, the sample weights for that thermodynamic state will be computed, i.e. \(\mu^k(x)\). Otherwise, this gives the unbiased sample weights \(\mu(x)\).

Parameters:

• dtrajs (list(np.ndarray)) – The list of discrete trajectories. dtrajs[i][n] contains the Markov state index of the \(n\)-th sample in the \(i\)-th trajectory. Sample weights are computed for each of the samples in the dtrajs.

• bias_matrices (list(np.ndarray)) – The bias energy matrices. bias_matrices[i][n, k] contains the bias energy of the \(n\)-th sample from the \(i\)-th trajectory, evaluated at thermodynamic state \(k\), i.e. \(b^k(x_{i,n})\).

• therm_state (int, optional) – The index of the thermodynamic state in which the sample weights need to be computed. If therm_state=-1, the unbiased sample weights are computed.

Returns:

sample_weights_log – The log of the statistical weight \(\mu(x)\) of each sample (i.e., the probability distribution over all samples: the sum over all sample weights equals one.)

Return type:

np.ndarray

Notes

The statistical distribution is given by

\[\mu(x) = \left( \sum_k R^k_{i(x)} \mathrm{exp}[f^k_{i(k)}-b^k(x)] \right)^{-1} \]

copy() → Model

Makes a deep copy of this model.

Returns:

A new copy of this model.

Return type:

copy

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 biased_conf_energies: ndarray

The estimated free energy per thermodynamic state and Markov state, \(f_k^i\), where \(k\) is the thermodynamic state index, and \(i\) the Markov state index.

property lagrangian_mult_log: ndarray

The estimated logarithm of the lagrange multipliers \(v_i^k\) of each Markov state for all thermodynamic states. lagrangian_mult_log[k,i] contains the lagrange multiplier of Markov state \(i\) in thermodynamic state \(k\).

property markov_state_energies: ndarray

The estimated free energy per Markov state, \(f^i\), where \(i\) is the Markov state index.

property modified_state_counts_log

The logarithm of the modified state counts \(R_i^k\) of each Markov state for all thermodynamic states. modified_state_counts_log[k,i] contains the state counts of Markov state \(i\) in thermodynamic state \(k\).

property msm_collection

The underlying MarkovStateModelCollection. Contains one Markov state model for each sampled thermodynamic state.

Getter:

The collection of markov state models containing one model for each thermodynamic state.

Type:

MarkovStateModelCollection

property therm_state_energies: ndarray

The estimated free energy per thermodynamic state, \(f_k\), where \(k\) is the thermodynamic state index.