pyemma.coordinates.transform.TICA¶

class pyemma.coordinates.transform.TICA(lag, output_dimension, epsilon=1e-06, force_eigenvalues_le_one=False)¶

Time-lagged independent component analysis (TICA)

Parameters:

tau (int) – lag time
output_dimension (int) – how many significant TICS to use to reduce dimension of input data
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.

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 r_i,\]

where \(r_i\) are the independent components and \(\lambda_i\) are their respective normalized time-autocorrelations. The eigenvalues are related to the relaxation timescale by

\[t_i = -\tau / \ln |\lambda_i|.\]

When used as a dimension reduction method, the input data is projected onto the dominant independent components.

__init__(lag, output_dimension, epsilon=1e-06, force_eigenvalues_le_one=False)¶

Methods

`__init__`(lag, output_dimension[, epsilon, ...])
`describe`(args, *kwargs)	Get a descriptive string representation of this class.
`dimension`()	output dimension
`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)	Maps the input data through the transformer to correspondingly shaped output data array/list.
`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
`trajectory_length`(itraj[, stride])	Returns the length of trajectory of the requested index.
`trajectory_lengths`([stride])	Returns the length of each trajectory.

Attributes

`chunksize`	chunksize defines how much data is being processed at once.
`data_producer`	where the transformer obtains its data.
`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

chunksize¶: chunksize defines how much data is being processed at once.

data_producer¶: where the transformer obtains its data.

describe(*args, **kwargs)¶: Get a descriptive string representation of this class.

dimension()¶: output dimension

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)

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
>>> %matplotlib inline # only for ipython notebook
>>>
>>> tica = coor.tica() # fill with some actual data!
>>> 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. If lag is used together with stride the operation will work as if the striding operation is applied before the time-lagged trajectory is shifted by lag 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 pyemma.coordinates.transfrom.TransformerIterator transformer iterator

lag¶: lag time of correlation matrix \(C_ au\)

map(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. 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)

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

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

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:	int
Return type:	length of each trajectory