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
Attributes
Whether to apply Bessel's correction for an unbiased estimator.
Whether to compute instantaneous correlations.
Whether to compute time lagged correlations with a defined
lagtime
.Whether to compute instantaneous correlations over the time-shifted chunks of the data.
" Whether the computation should be restricted to diagonal entries (autocorrelations) only.
Property reporting whether this estimator contains an estimated model.
Determines whether this estimator also computes time-lagged covariances.
The lagtime of the estimator.
Shortcut to
fetch_model()
.The depth of the moments storage.
Whether to remove the sample mean, i.e., compute mean-free correlations.
Whether to symmetrize correlations.
The sparse mode of the estimator.
Methods
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:
- 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:
- 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 thedata
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
andcompute_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