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) C @ w = lambda * R @ w where C is the signal covariance and R is a reference covariance. Two modes are supported:

• Leadfield mode (recommended, true GEDAI): R = L @ L.T, where L is the EEG forward/leadfield gain matrix. Because lambda = (w.T @ C @ w) / (w.T @ R @ w), components with large lambda carry sensor power that the brain’s theoretical source model cannot explain and are treated as artifacts; components with small lambda are leadfield-aligned and are kept as brain signal. Use fit_from_leadfield() to fit in this mode.

• Band-filter mode (Cohen-style GED): C = R_band and R = R_broad (broadband EEG covariance, Tikhonov-regularised). Components with large lambda maximise the target-band-to-broadband ratio, while components with small lambda capture broadband noise. Use fit() or fit_from_raw() for this mode.

In both modes the unmixing matrix W (spatial filters) and activation patterns A = pinv(W.T) are stored after fitting. Denoising zeroes the selected artifact columns of A and reconstructs clean sensor data as x_hat = A_clean @ W.T @ 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 artifact/noise components according to the fitted mode.
fit(data_broadband, data_band)	Estimate spatial filters from baseline data (band-filter mode).
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 (band-filter mode).

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 R = L @ L.T where L is the leadfield gain matrix. Because the GEP solves C @ w = lambda * R @ w, components whose eigenvalues are large have excess sensor variance relative to the theoretical brain source model and are treated as artifacts; components with small eigenvalues are leadfield-aligned and are kept as brain signal.

Parameters:

datandarray, shape (n_channels, n_samples)

Broadband baseline EEG/MEG recording.

leadfieldndarray, shape (n_channels, n_sources)

Forward solution gain matrix 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 artifact/noise components according to the fitted mode.

In leadfield mode (fit_from_leadfield()), eigenvalues measure the ratio of observed sensor variance to theoretical brain variance (C @ w = lambda * R_lead @ w), so components with the largest eigenvalues are artifact candidates, and the top n_noise components [0, ..., n_noise - 1] are returned.

In band-filter mode (fit() / fit_from_raw()), components with the smallest eigenvalues capture the least band-specific activity and are returned as broadband noise candidates [n_channels - n_noise, ..., n_channels - 1].

Parameters:

n_noiseint, default 1

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,)

Topography of the artifact; components whose activation pattern correlates with it above threshold are suppressed.

thresholdfloat, default 0.7

Absolute-correlation threshold.

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).