pyemma.coordinates.transform.TICA¶
-
class
pyemma.coordinates.transform.
TICA
(lag, dim=-1, var_cutoff=0.95, kinetic_map=True, epsilon=1e-06, force_eigenvalues_le_one=False, mean=None)¶ Time-lagged independent component analysis (TICA)
-
__init__
(lag, dim=-1, var_cutoff=0.95, kinetic_map=True, epsilon=1e-06, force_eigenvalues_le_one=False, mean=None)¶ Time-lagged independent component analysis (TICA) [1], [2], [3].
Parameters: - tau (int) – lag time
- dim (int, optional, default -1) – Maximum number of significant independent components to use to reduce dimension of input data. -1 means all numerically available dimensions (see epsilon) will be used unless reduced by var_cutoff. Setting dim to a positive value is exclusive with var_cutoff.
- var_cutoff (float in the range [0,1], optional, default 0.95) – Determines the number of output dimensions by including dimensions until their cumulative kinetic variance exceeds the fraction subspace_variance. var_cutoff=1.0 means all numerically available dimensions (see epsilon) will be used, unless set by dim. Setting var_cutoff smaller than 1.0 is exclusive with dim
- kinetic_map (bool, optional, default True) – Eigenvectors will be scaled by eigenvalues. As a result, Euclidean distances in the transformed data approximate kinetic distances [4]. This is a good choice when the data is further processed by clustering.
- epsilon (float) – eigenvalue norm cutoff. Eigenvalues of C0 with norms <= epsilon will be cut off. The remaining number of eigenvalues define the size of the output.
- force_eigenvalues_le_one (boolean) – Compute covariance matrix and time-lagged covariance matrix such that the generalized eigenvalues are always guaranteed to be <= 1.
- mean (ndarray, optional, default None) – Optionally pass pre-calculated means to avoid their re-computation. The shape has to match the input dimension.
Notes
Given a sequence of multivariate data \(X_t\), computes the mean-free covariance and time-lagged covariance matrix:
\[\begin{split}C_0 &= (X_t - \mu)^T (X_t - \mu) \\ C_{\tau} &= (X_t - \mu)^T (X_{t + \tau} - \mu)\end{split}\]and solves the eigenvalue problem
\[C_{\tau} r_i = C_0 \lambda_i(tau) r_i,\]where \(r_i\) are the independent components and \(\lambda_i(tau)\) are their respective normalized time-autocorrelations. The eigenvalues are related to the relaxation timescale by
\[t_i(tau) = -\tau / \ln |\lambda_i|.\]When used as a dimension reduction method, the input data is projected onto the dominant independent components.
References
[1] (1, 2) Perez-Hernandez G, F Paul, T Giorgino, G De Fabritiis and F Noe. 2013. Identification of slow molecular order parameters for Markov model construction J. Chem. Phys. 139, 015102. doi:10.1063/1.4811489 [2] (1, 2) Schwantes C, V S Pande. 2013. Improvements in Markov State Model Construction Reveal Many Non-Native Interactions in the Folding of NTL9 J. Chem. Theory. Comput. 9, 2000-2009. doi:10.1021/ct300878a [3] (1, 2) L. Molgedey and H. G. Schuster. 1994. Separation of a mixture of independent signals using time delayed correlations Phys. Rev. Lett. 72, 3634. [4] Noe, F. and C. Clementi. 2015. Kinetic distance and kinetic maps from molecular dynamics simulation http://arxiv.org/abs/1506.06259
Methods
__init__
(lag[, dim, var_cutoff, ...])Time-lagged independent component analysis (TICA) [1], [2], [3]. describe
(*args, **kwargs)Get a descriptive string representation of this class. dimension
()output dimension fit
(X, **kwargs)For compatibility with sklearn fit_transform
(X, **kwargs)For compatibility with sklearn get_output
([dimensions, stride])Maps all input data of this transformer and returns it as an array or list of arrays. iterator
([stride, lag])Returns an iterator that allows to access the transformed data. map
(X)Deprecated: use transform(X) n_frames_total
([stride])Returns total number of frames. number_of_trajectories
()Returns the number of trajectories. output_type
()By default transformers return single precision floats. parametrize
([stride])Parametrize this Transformer register_progress_callback
(call_back[, stage])Registers the progress reporter. trajectory_length
(itraj[, stride])Returns the length of trajectory of the requested index. trajectory_lengths
([stride])Returns the length of each trajectory. transform
(X)Maps the input data through the transformer to correspondingly shaped output data array/list. Attributes
chunksize
chunksize defines how much data is being processed at once. cumvar
Cumulative sum of the the TICA eigenvalues data_producer
where the transformer obtains its data. eigenvalues
Eigenvalues of the TICA problem (usually denoted \(\lambda\) eigenvectors
Eigenvectors of the TICA problem, columnwise feature_TIC_correlation
Instantaneous correlation matrix between input features and TICs in_memory
are results stored in memory? lag
lag time of correlation matrix \(C_{ au}\) mean
mean of input features name
The name of this instance ntraj
timescales
Implied timescales of the TICA transformation -
chunksize
¶ chunksize defines how much data is being processed at once.
-
cumvar
¶ Cumulative sum of the the TICA eigenvalues
Returns: cumvar Return type: 1D np.array
-
data_producer
¶ where the transformer obtains its data.
-
describe
(*args, **kwargs)¶ Get a descriptive string representation of this class.
-
dimension
()¶ output dimension
-
eigenvalues
¶ Eigenvalues of the TICA problem (usually denoted \(\lambda\)
Returns: eigenvalues Return type: 1D np.array
-
eigenvectors
¶ Eigenvectors of the TICA problem, columnwise
Returns: eigenvectors Return type: (N,M) ndarray
-
feature_TIC_correlation
¶ Instantaneous correlation matrix between input features and TICs
Denoting the input features as \(X_i\) and the TICs as \(\theta_j\), the instantaneous, linear correlation between them can be written as
\[\mathbf{Corr}(X_i, \mathbf{\theta}_j) = \frac{1}{\sigma_{X_i}}\sum_l \sigma_{X_iX_l} \mathbf{U}_{li}\]The matrix \(\mathbf{U}\) is the matrix containing, as column vectors, the eigenvectors of the TICA generalized eigenvalue problem .
Returns: feature_TIC_correlation – correlation matrix between input features and TICs. There is a row for each feature and a column for each TIC. Return type: ndarray(n,m)
-
fit
(X, **kwargs)¶ For compatibility with sklearn
-
fit_transform
(X, **kwargs)¶ For compatibility with sklearn
-
get_output
(dimensions=slice(0, None, None), stride=1)¶ Maps all input data of this transformer and returns it as an array or list of arrays.
Parameters: - dimensions (list-like of indexes or slice) – indices of dimensions you like to keep, default = all
- stride (int) – only take every n’th frame, default = 1
Returns: output – the mapped data, where T is the number of time steps of the input data, or if stride > 1, floor(T_in / stride). d is the output dimension of this transformer. If the input consists of a list of trajectories, Y will also be a corresponding list of trajectories
Return type: ndarray(T, d) or list of ndarray(T_i, d)
Notes
- This function may be RAM intensive if stride is too large or too many dimensions are selected.
- if in_memory attribute is True, then results of this methods are cached.
Example
plotting trajectories
>>> import pyemma.coordinates as coor >>> import matplotlib.pyplot as plt
Fill with some actual data!
>>> tica = coor.tica() >>> trajs = tica.get_output(dimensions=(0,), stride=100) >>> for traj in trajs: ... plt.figure() ... plt.plot(traj[:, 0])
-
in_memory
¶ are results stored in memory?
-
iterator
(stride=1, lag=0)¶ Returns an iterator that allows to access the transformed data.
Parameters: - stride (int) – Only transform every N’th frame, default = 1
- lag (int) – Configure the iterator such that it will return time-lagged data
with a lag time of
lag
. Iflag
is used together with stride the operation will work as if the striding operation is applied before the time-lagged trajectory is shifted bylag
steps. Therefore the effective lag time will be stride*lag.
Returns: iterator – If lag = 0, a call to the .next() method of this iterator will return the pair (itraj, X) : (int, ndarray(n, m)), where itraj corresponds to input sequence number (eg. trajectory index) and X is the transformed data, n = chunksize or n < chunksize at end of input.
If lag > 0, a call to the .next() method of this iterator will return the tuple (itraj, X, Y) : (int, ndarray(n, m), ndarray(p, m)) where itraj and X are the same as above and Y contain the time-lagged data.
Return type: a
TransformerIterator
-
lag
¶ lag time of correlation matrix \(C_{ au}\)
-
logger
¶ The logger for this class instance
-
map
(X)¶ Deprecated: use transform(X)
Maps the input data through the transformer to correspondingly shaped output data array/list.
-
mean
¶ mean of input features
-
n_frames_total
(stride=1)¶ Returns total number of frames.
Parameters: stride (int) – return value is the number of frames in trajectories when running through them with a step size of stride. Returns: int Return type: n_frames_total
-
name
¶ The name of this instance
-
number_of_trajectories
()¶ Returns the number of trajectories.
Returns: int Return type: number of trajectories
-
output_type
()¶ By default transformers return single precision floats.
-
parametrize
(stride=1)¶ Parametrize this Transformer
-
register_progress_callback
(call_back, stage=0)¶ Registers the progress reporter.
Parameters: - call_back (function) –
This function will be called with the following arguments:
- stage (int)
- instance of pyemma.utils.progressbar.ProgressBar
- optional *args and named keywords (**kw), for future changes
- stage (int, optional, default=0) – The stage you want the given call back function to be fired.
- call_back (function) –
-
timescales
¶ Implied timescales of the TICA transformation
For each \(i\)-th eigenvalue, this returns
\[t_i = -\frac{\tau}{\log(|\lambda_i|)}\]where \(\tau\) is the
lag
of the TICA object and \(\lambda_i\) is the i-theigenvalue
of the TICA object.Returns: timescales – numpy array with the implied timescales. In principle, one should expect as many timescales as input coordinates were available. However, less eigenvalues will be returned if the TICA matrices were not full rank or var_cutoff
was parsedReturn type: 1D np.array
-
trajectory_length
(itraj, stride=1)¶ Returns the length of trajectory of the requested index.
Parameters: - itraj (int) – trajectory index
- stride (int) – return value is the number of frames in the trajectory when running through it with a step size of stride.
Returns: int
Return type: length of trajectory
-
trajectory_lengths
(stride=1)¶ Returns the length of each trajectory.
Parameters: stride (int) – return value is the number of frames of the trajectories when running through them with a step size of stride. Returns: array(dtype=int) Return type: containing length of each trajectory
-
transform
(X)¶ Maps the input data through the transformer to correspondingly shaped output data array/list.
Parameters: X (ndarray(T, n) or list of ndarray(T_i, n)) – The input data, where T is the number of time steps and n is the number of dimensions. If a list is provided, the number of time steps is allowed to vary, but the number of dimensions are required to be to be consistent. Returns: Y – The mapped data, where T is the number of time steps of the input data and d is the output dimension of this transformer. If called with a list of trajectories, Y will also be a corresponding list of trajectories Return type: ndarray(T, d) or list of ndarray(T_i, d)
-