pyeeg.utils.lag_matrix

pyeeg.utils.lag_matrix(x, lags=(0, 1), mode='full', fill_value=0.0, block_order='lags', **kwargs)

Helper function to create a Toeplitz matrix of lagged time series.

The lag can be arbitrarily spaced. Check other functions to create series of lags whether they are contiguous or sparsely spanning a time window lag_span() and lag_sparse().

Parameters:

• x (ndarray (nsamples x nfeats)) – Multivariate data

• lags (list) – Shift in _samples_ to be applied to data. Negative shifts are lagged in the past, positive shits in the future, and a shift of 0 represents the data array as it is in the input data.

• fill_value (float) – What value to use to fill entries which are not defined (Default: NaN).

• mode (str) – ‘valid’ or ‘full’ (default: ‘valid’). ‘valid’ returns only the part of the lagged matrix that is valid (i.e. no NaN values). ‘full’ returns the full lagged matrix, including missing values, which are filled with fill_value.

• block_order (str) –

  Column ordering for multi-feature inputs: - ‘lags’ (default): group by lag first — [feat0_lag0, feat1_lag0, feat0_lag1, feat1_lag1, …]

  This is the legacy ordering used by TRFEstimator.

  • ’features’: group by feature first — [feat0_lag0, feat0_lag1, …, feat1_lag0, feat1_lag1, …] Useful for banded ridge regularization (per-feature alpha).

  Ignored for single-feature inputs.

• **kwargs (keyword arguments) – Additional arguments to be passed to the function for backward compatibility. For example, filling and drop_missing are deprecated and will be removed in future versions.

Returns:

lagged – Matrix of lagged time series.

Return type:

ndarray (nsamples_new x nfeats*len(lag_samples))

Raises:

ValueError – If mode is not ‘valid’ or ‘full’.

Examples

Default ordering (grouped by lag): >>> data = np.asarray([[1,2,3,4,5,6],[7,8,9,10,11,12]]).T >>> out = lag_matrix(data, (-1, 0, 2), mode=’full’) >>> out # doctest: +NORMALIZE_WHITESPACE array([[ 2, 8, 1, 7, 0, 0],

[ 3, 9, 2, 8, 0, 0], [ 4, 10, 3, 9, 1, 7], [ 5, 11, 4, 10, 2, 8], [ 6, 12, 5, 11, 3, 9], [ 0, 0, 6, 12, 4, 10]])

Per-feature ordering (grouped by feature): >>> out_feat = lag_matrix(data, (-1, 0, 2), mode=’full’, block_order=’features’) >>> out_feat # doctest: +NORMALIZE_WHITESPACE array([[ 2, 1, 0, 8, 7, 0],

[ 3, 2, 0, 9, 8, 0], [ 4, 3, 1, 10, 9, 7], [ 5, 4, 2, 11, 10, 8], [ 6, 5, 3, 12, 11, 9], [ 0, 6, 4, 0, 12, 10]])