mne_rt.tools.GEDAIDenoiser

class mne_rt.tools.GEDAIDenoiser(n_channels: int, shrinkage: float = 0.01)

Bases: object

Artifact removal via Generalised Eigendecomposition-based Artifact Identification (GEDAI).

Solves the generalised eigenvalue problem (GEP):

\[\mathbf{C}\,\mathbf{w} = \lambda\,\mathbf{R}\,\mathbf{w}\]

where \(\mathbf{C}\) is the signal covariance and \(\mathbf{R}\) is a reference covariance. Two modes are supported:

• Leadfield mode (recommended, true GEDAI): \(\mathbf{R} = \mathbf{L}\mathbf{L}^\top\), where \(\mathbf{L}\) is the EEG forward/leadfield gain matrix. Components with large \(\lambda\) are well-explained by the brain’s theoretical source model and are kept; components with small \(\lambda\) are not leadfield-aligned and are treated as artifacts. Use fit_from_leadfield() to fit in this mode.

• Band-filter mode (Cohen-style GED): \(\mathbf{C} = \mathbf{R}_{\mathrm{band}}\) and \(\mathbf{R} = \mathbf{R}_{\mathrm{broad}}\) (broadband EEG covariance, Tikhonov-regularised). Components with large \(\lambda\) maximise the target-band-to-broadband ratio. Use fit() or fit_from_raw() for this mode.

In both modes the unmixing matrix \(\mathbf{W}\) (spatial filters) and activation patterns \(\mathbf{A} = (\mathbf{W}^\top)^+\) are stored after fitting. Denoising zeroes the selected artifact columns of \(\mathbf{A}\) and reconstructs clean sensor data as \(\hat{\mathbf{x}} = \mathbf{A}_{\mathrm{clean}}\,\mathbf{W}^\top\mathbf{x}\).

Parameters:

n_channelsint

Number of EEG/MEG channels.

shrinkagefloat, default 0.01

Tikhonov regularisation strength applied to the reference covariance before solving the GEP. Prevents ill-conditioning when the covariance matrix is rank-deficient.

References

Ros, T., Férat, V., Huang, Y., et al. (2025). Return of the GEDAI: Unsupervised EEG Denoising based on Leadfield Filtering. bioRxiv. https://doi.org/10.1101/2025.10.04.680449

Cohen, M. X. (2022). A tutorial on generalized eigendecomposition for denoising, contrast enhancement, and dimension reduction in multichannel electrophysiology. NeuroImage, 247, 118809.

__init__(n_channels: int, shrinkage: float = 0.01) → None

Methods

__init__(n_channels[, shrinkage])
denoise(data, artifact_idx)	Suppress artifact components and reconstruct sensor data.
find_artifact_components(template_map[, ...])	Identify artifact components by correlation with a spatial template.
find_noise_components([n_noise])	Return indices of the n_noise components with smallest eigenvalues.
fit(data_broadband, data_band)	Estimate spatial filters from baseline data.
fit_from_leadfield(data, leadfield)	Fit using the forward/leadfield matrix as the reference covariance.
fit_from_raw(data, sfreq, band)	Convenience wrapper: bandpass-filter data internally then call fit.
inverse_transform(components)	Reconstruct sensor-space data from components.
transform(data)	Project data into component space.
update_and_denoise(data, template_map[, ...])	Identify blink/artifact components then denoise in one call.

Attributes

activation_patterns	Activation patterns A = pinv(W.T), shape (n_channels, n_channels).
eigenvalues	Sorted eigenvalues (descending) from the GED.
spatial_filters	Spatial filters W, shape (n_channels, n_channels).

fit(data_broadband: ndarray, data_band: ndarray) → GEDAIDenoiser

Estimate spatial filters from baseline data.

Parameters:

data_broadbandndarray, shape (n_channels, n_samples)

Broadband (or noise-reference) baseline data.

data_bandndarray, shape (n_channels, n_samples)

Band-filtered baseline data (the signal of interest).

Returns:

self

fit_from_leadfield(data: ndarray, leadfield: ndarray) → GEDAIDenoiser

Fit using the forward/leadfield matrix as the reference covariance.

This is the true GEDAI mode described in Ros et al. (2025). The reference covariance is constructed as \(\mathbf{R} = \mathbf{L}\mathbf{L}^\top\) where \(\mathbf{L}\) is the leadfield gain matrix. Components whose eigenvalues are large are well-aligned with the theoretical brain source model and are treated as signal; components with small eigenvalues are artifact candidates.

Parameters:

datandarray, shape (n_channels, n_samples)

Broadband baseline EEG/MEG recording.

leadfieldndarray, shape (n_channels, n_sources)

Forward solution gain matrix \(\mathbf{L}\) — the fwd['sol']['data'] array from an MNE forward solution.

Returns:

self

fit_from_raw(data: ndarray, sfreq: float, band: tuple[float, float]) → GEDAIDenoiser

Convenience wrapper: bandpass-filter data internally then call fit.

Parameters:

datandarray, shape (n_channels, n_samples)

Baseline recording (broadband).

sfreqfloat

Sampling frequency in Hz.

band(low, high)

Target frequency band in Hz.

Returns:

self

transform(data: ndarray) → ndarray

Project data into component space.

Parameters:

datandarray, shape (n_channels, n_samples)

Returns:

componentsndarray, shape (n_channels, n_samples)

inverse_transform(components: ndarray) → ndarray

Reconstruct sensor-space data from components.

Parameters:

componentsndarray, shape (n_channels, n_samples)

Returns:

datandarray, shape (n_channels, n_samples)

find_artifact_components(template_map: ndarray, threshold: float = 0.7) → tuple[list[int], ndarray]

Identify artifact components by correlation with a spatial template.

Parameters:

template_mapndarray, shape (n_channels,)

Known topography of the artifact (e.g., blink, ECG).

thresholdfloat

Absolute-correlation threshold.

Returns:

artifact_idxlist of int

corrsndarray, shape (n_channels,)

find_noise_components(n_noise: int = 1) → list[int]

Return indices of the n_noise components with smallest eigenvalues.

These components capture the least band-specific activity and are candidates for broadband noise.

Parameters:

n_noiseint

Number of components to flag.

Returns:

list of int

denoise(data: ndarray, artifact_idx: list[int]) → ndarray

Suppress artifact components and reconstruct sensor data.

Parameters:

datandarray, shape (n_channels, n_samples)

artifact_idxlist of int

Component indices to zero out.

Returns:

data_cleanndarray, shape (n_channels, n_samples)

update_and_denoise(data: ndarray, template_map: ndarray, threshold: float = 0.7) → ndarray

Identify blink/artifact components then denoise in one call.

Parameters:

datandarray, shape (n_channels, n_samples)

template_mapndarray, shape (n_channels,)

thresholdfloat

Returns:

data_cleanndarray, shape (n_channels, n_samples)

property eigenvalues: ndarray

Sorted eigenvalues (descending) from the GED.

property spatial_filters: ndarray

Spatial filters W, shape (n_channels, n_channels).

property activation_patterns: ndarray

Activation patterns A = pinv(W.T), shape (n_channels, n_channels).