mne_denoise.dss.compute_dss#

mne_denoise.dss.compute_dss(covariance_baseline: ndarray, covariance_biased: ndarray, *, n_components: int | None = None, rank: int | None = None, reg: float = 1e-09) → tuple[ndarray, ndarray, ndarray][source]#

Compute DSS spatial filters from baseline and biased covariances.

This implements the core Linear DSS algorithm as described in Särelä & Valpola (2005) [1].

The algorithm finds a linear transform (spatial filters) that maximizes the biased variance (signal) relative to total/baseline variance (noise).

The process corresponds to Equation 7 in de Cheveigné & Simon (2008) [2]:

\[\begin{split}\\tilde{S}(t) = P Q R_2 N_2 R_1 N_1 S(t)\end{split}\]

where:

N1 (Initial Normalization): Handled externally (e.g. DSS(normalize_input=True)). Ensures equal weight for each sensor.
R1 (First PCA): Rotation derived from baseline covariance (Sphering/Whitening PCA). Discards components with negligible power.
N2 (Whitening): Normalization to obtain orthonormal “spatially whitened” vectors.
R2 (Second PCA): Rotation derived from biased covariance in the whitened space.
Q (Selector): Selection of the top n_components with highest bias score.
P (Projection): Projection back to sensor space (Spatial Patterns).

Parameters:

covariance_baseline (ndarray) – Baseline covariance.
covariance_biased (ndarray) – Biased covariance.
n_components (int, optional) – Number of DSS components to return (The Q selector step). If None, return all.
rank (int, optional) – Rank for whitening stage. If None, auto-determined from data.
reg (float) – Regularization threshold. Default 1e-9.

Returns:

dss_filters (ndarray, shape (n_components, n_channels)) – DSS spatial filters (unmixing matrix transposed). Corresponds to the combined transform \(Q R_2 N_2 R_1\). Apply as: sources = dss_filters @ data.
dss_patterns (ndarray, shape (n_channels, n_components)) – DSS spatial patterns (mixing matrix). Corresponds to the projection matrix P. Note: These are returned in original sensor units (not normalized), satisfying the identity \(X_{rec} = Patterns \times Sources\).
eigenvalues (ndarray, shape (n_components,)) – DSS eigenvalues (ratio of biased power to baseline power).

Examples

>>> import numpy as np
>>> from mne_denoise.dss import compute_dss, compute_covariance
>>> # Generate synthetic data (n_channels, n_times)
>>> data = np.random.randn(10, 1000)
>>> # Compute covariances
>>> cov_baseline = compute_covariance(data)
>>> # Biased covariance: trial-averaged standard example or filtering
>>> cov_biased = compute_covariance(data)  # Just a placeholder
>>> # Compute DSS
>>> filters, patterns, evs = compute_dss(cov_baseline, cov_biased, n_components=5)