mne_denoise.dss.TimeShiftDSS#

class mne_denoise.dss.TimeShiftDSS(*, lag_samples: Sequence[int] | None = None, lag_times: Sequence[float] | None = None, sfreq: float | None = None, n_components: int, rank: int, n_select: int | None = None, component_action: str = 'extract', center: bool = False, distortion_control: str | None = None, reg: float = 1e-09, verbose: bool | str | int | None = None)[source]#

Lag-augmented DSS estimator for repeated trials.

The estimator augments each sensor with delayed copies, fits a trial-average DSS decomposition in the resulting spatiotemporal space, and supports source extraction or sensor-space retain/subtract operations.

Parameters:

lag_samplessequence of int or None, default=None: Explicit lag grid in samples. It must contain zero and a nonzero lag.
lag_timessequence of float or None, default=None: Explicit lag grid in seconds. Exactly one lag representation is required; values must lie on the sampling grid.
sfreqfloat or None, default=None: Sampling frequency for array data when lag_times is used.
n_componentsint: Number of lag-space DSS components.
rankint: Whitening rank in the augmented feature space.
n_selectint or None, default=None: Leading components used by score, retain, or subtract.
component_action{“extract”, “retain”, “subtract”}, default=”extract”: Source extraction or sensor-space operation.
centerbool, default=False: Fit and reuse one augmented-feature mean when true.
distortion_control{None, “cca”}, default=None: Optional CCA rotation of the fitted reproducible subspace.
regfloat, default=1e-9: Relative numerical rank tolerance.
verbosebool, str, int, or None, default=None: Logging level.

See also

DSS: Ordinary spatial DSS without lag augmentation.
AverageBias: Trial-average bias used by ordinary DSS.

Notes

Input must be repeated-trial data: NumPy arrays use (n_channels, n_times, n_epochs) and MNE Epochs use their native layout. Lags define the common valid support; samples outside it are unchanged by sensor-space operations. A sampling frequency is required when lags are specified in seconds [1].

References

Examples

>>> import numpy as np
>>> from mne_denoise.dss import TimeShiftDSS
>>> rng = np.random.default_rng(0)
>>> epochs = rng.standard_normal((8, 200, 20))
>>> model = TimeShiftDSS(
...     lag_samples=[0, 1, 2],
...     n_components=2,
...     rank=4,
...     n_select=1,
...     component_action="extract",
... )
>>> sources = model.fit_transform(epochs)

Fit the lag-augmented repeated-trial DSS decomposition.

Parameters:

Xmne.BaseEpochs or ndarray: Repeated-trial input.
yNone, default=None: Ignored for scikit-learn compatibility.
sample_weightndarray or None, default=None: Non-negative weights with shape (n_times,) or (n_times, n_epochs).
verbosebool, str, int, or None, default=None: Logging level for this call.

Returns:

TimeShiftDSS: The fitted estimator.

score(X: BaseEpochs | np.ndarray, y: None = None, *, sample_weight: np.ndarray | None = None) → float[source]#

Score the fitted leading subspace on repeated trials.

Parameters:

Xmne.BaseEpochs or ndarray: Held-out repeated-trial input.
yNone, default=None: Ignored for scikit-learn compatibility.
sample_weightndarray or None, default=None: Optional observation weights.

Returns:

float: Weighted trial-average power divided by weighted total power for the selected leading components.

Apply the fitted lag-augmented DSS operation.

Parameters:

Xmne.BaseEpochs or ndarray: Repeated-trial input compatible with fit().
verbosebool, str, int, or None, default=None: Logging level for this call.

Returns:

ndarray or mne.BaseEpochs: Sources or sensor-space output according to component_action; samples outside the common lag support are preserved.