class Covariance

class deeptime.covariance.Covariance(lagtime: int = 0, compute_c00: bool = True, compute_c0t: bool = False, compute_ctt: bool = False, remove_data_mean: bool = False, reversible: bool = False, bessels_correction: bool = True, sparse_mode: str = 'auto', ncov: int = 5, diag_only: bool = False, model=None)

Compute (potentially lagged) covariances between data in an online fashion.

This means computing

\[\mathrm{cov}[ X_t, Y_t ] = \mathbb{E}[(X_t - \mathbb{E}[X_t])(Y_t - \mathbb{E}[Y_t])], \]

where \(X_t\) and \(Y_t\) are contiguous blocks of frames from the timeseries data. The estimator implements the online algorithm proposed in [1], report available here.

Parameters:

• lagtime (int, default=0) – The lagtime, must be \(\geq 0\) .

• compute_c00 (bool, optional, default=True) – Compute instantaneous correlations over the first part of the data. If lagtime ==0, use all of the data.

• compute_c0t (bool, optional, default=False) – Compute lagged correlations. Does not work with lagtime ==0.

• compute_ctt (bool, optional, default=False) – Compute instantaneous covariance over the time-shifted chunks of the data. Does not work with lagtime ==0.

• remove_data_mean (bool, optional, default=False) – Subtract the sample mean from the time series (mean-free correlations).

• reversible (bool, optional, default=False) – Symmetrize correlations, i.e., use estimates defined by \(\sum_t X_t + Y_t\) and second moment matrices defined by \(X_t^\top X_t + Y_t^\top Y_t\) and \(Y_t^\top X_t + X_t^\top Y_t\) .

• bessels_correction (bool, optional, default=True) – Use Bessel’s correction for correlations in order to use an unbiased estimator.

• sparse_mode (str, optional, default='auto') –

  one of:

  • ’dense’ : always use dense mode

  • ’auto’ : automatic

  • ’sparse’ : always use sparse mode if possible

• ncov (int, optional, default=5) – Depth of moment storage. Moments computed from each chunk will be combined with Moments of similar statistical weight using the pairwise combination algorithm described in [1].

• diag_only (bool) – If True, the computation is restricted to the diagonal entries (autocorrelations) only.

• model (CovarianceModel, optional, default=None) – A model instance with which the estimator can be initialized.

References

[1] (1,2)

Tony F Chan, Gene Howard Golub, and Randall J LeVeque. Updating formulae and a pairwise algorithm for computing sample variances. In COMPSTAT 1982 5th Symposium held at Toulouse 1982, 30–41. Springer, 1982.

Attributes

bessels_correction	Whether to apply Bessel's correction for an unbiased estimator.
compute_c00	Whether to compute instantaneous correlations.
compute_c0t	Whether to compute time lagged correlations with a defined lagtime.
compute_ctt	Whether to compute instantaneous correlations over the time-shifted chunks of the data.
diag_only	" Whether the computation should be restricted to diagonal entries (autocorrelations) only.
has_model	Property reporting whether this estimator contains an estimated model.
is_lagged	Determines whether this estimator also computes time-lagged covariances.
lagtime	The lagtime of the estimator.
model	Shortcut to fetch_model().
ncov	The depth of the moments storage.
remove_data_mean	Whether to remove the sample mean, i.e., compute mean-free correlations.
reversible	Whether to symmetrize correlations.
sparse_mode	The sparse mode of the estimator.

Methods

fetch_model()	Finalizes the covariance computation by aggregating all moment storages.
fit(data[, lagtime, weights, n_splits, ...])	Computes covariances for the input data and produces a new model.
fit_fetch(data, **kwargs)	Fits the internal model on data and subsequently fetches it in one call.
get_params([deep])	Get the parameters.
partial_fit(data[, weights, column_selection])	Incrementally update the estimates.
set_params(**params)	Set the parameters of this estimator.

fetch_model() → CovarianceModel

Finalizes the covariance computation by aggregating all moment storages.

Returns:

model – The covariance model.

Return type:

CovarianceModel

fit(data, lagtime=None, weights=None, n_splits=None, column_selection=None)

Computes covariances for the input data and produces a new model. If an existing model should be updated, call partial_fit().

Parameters:

• data (array_like or list of array_like) – The input data. If it is a list of trajectories, all elements of the list must have the same dtype and size in the second dimension, i.e., the elements of [x.shape[1] for x in data] must all be equal.

• lagtime (int, optional, default=None) – Override for lagtime.

• weights (array_like or list of array_like or object, optional, default=None) –

  • Optional weights for the input data. Must be of matching shape.

  • Can also be another arbitrary object. The only requirement is that weights possesses a method weights(X), that accepts a trajectory X (np.ndarray(T, n)) and returns a vector of re-weighting factors (np.ndarray(T,)). See, e.g.,

    • KoopmanEstimator

• n_splits (int, optional, default=None) – The number of times the data is split uniformly when performing the covariance estimation. If no value is given, the data is not split.

• column_selection (ndarray, optional, default=None) – Columns of the trajectories to restrict estimation to. Must be given in terms of an index array.

Returns:

self – Reference to self.

Return type:

Covariance

fit_fetch(data, **kwargs)

Fits the internal model on data and subsequently fetches it in one call.

Parameters:

• data (array_like) – Data that is used to fit the model.

• **kwargs – Additional arguments to fit().

Returns:

The estimated model.

Return type:

model

get_params(deep=False)

Get the parameters.

Returns:

params – Parameter names mapped to their values.

Return type:

mapping of string to any

partial_fit(data, weights=None, column_selection=None)

Incrementally update the estimates. For a detailed description of the parameters, see fit() with the exception of the data argument, it must be a ndarray and cannot be a list of ndarray.

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 bessels_correction: bool

Whether to apply Bessel’s correction for an unbiased estimator.

Type:

bool

property compute_c00: bool

Whether to compute instantaneous correlations.

Type:

bool

property compute_c0t: bool

Whether to compute time lagged correlations with a defined lagtime.

Type:

bool

property compute_ctt: bool

Whether to compute instantaneous correlations over the time-shifted chunks of the data.

Type:

bool

property diag_only: bool

“ Whether the computation should be restricted to diagonal entries (autocorrelations) only.

Type:

bool

property has_model: bool

Property reporting whether this estimator contains an estimated model. This assumes that the model is initialized with None otherwise.

Type:

bool

property is_lagged: bool

Determines whether this estimator also computes time-lagged covariances.

Type:

bool

property lagtime: int

The lagtime of the estimator. This attribute determines how big the temporal difference for timelagged autocorrelations are.

Getter:

Yields the currently selected lagtime.

Setter:

Sets a new lagtime, must be \(\geq 0\), for compute_c0t and compute_ctt it must be \(> 0\).

Type:

int

property model

Shortcut to fetch_model().

property ncov: int

The depth of the moments storage.

Type:

int

property remove_data_mean: bool

Whether to remove the sample mean, i.e., compute mean-free correlations.

Type:

bool

property reversible: bool

Whether to symmetrize correlations.

Type:

bool

property sparse_mode: str

The sparse mode of the estimator. Can be one of ‘auto’, ‘sparse’, and ‘dense’.

Type:

str