gedai.gedai.Gedai

class gedai.gedai.Gedai(engine='auto')

Generalized Eigenvalue De-Artifacting Instrument.

See [1].

Parameters:

engine“auto” | “torch” | “numpy”, default=”auto”

Computation engine for generalized eigendecomposition, batched SENSAI evaluation, and wavelet decomposition. If "auto" (default), uses PyTorch CPU acceleration when installed, and falls back cleanly to NumPy otherwise.

Attributes

ch_names	Get the channel names used during fitting.
summary	Formatted ASCII summary table of the model fitting metrics.
threshold	Get the eigenvalue threshold used for cleaning.

Methods

fit_epochs(epochs[, picks, reference_cov, ...])	Fit the GEDAI model to the epochs.
fit_raw(raw[, picks, duration, overlap, ...])	Fit the GEDAI model to the raw data.
fit_summary()	Compatibility wrapper for the fitted-model summary.
plot_fit()	Plot the fitting results.
plot_sensai(raw_before[, raw_after, ...])	Plot SENSAI subspace similarity and manifold classification.
transform_epochs(epochs[, n_jobs, verbose, ...])	Transform epochs data using the fitted model.
transform_raw(raw[, overlap, n_jobs, ...])	Transform raw data using the fitted model.

References

[1]

Tomas Ros, Victor Férat, Yingqi Huang, Cristina Colangelo, Seyed Mostafa Kia, Thomas Wolfers, Serge Vulliemoz, and Abele Michela. Return of the gedai: unsupervised eeg denoising based on leadfield filtering. bioRxiv, 2025. doi:10.1101/2025.10.04.680449.

fit_epochs(epochs, picks='eeg', reference_cov='leadfield', sensai_method='optimize', noise_multiplier='auto', sensai_bounds=(-6.0, 12.0), sensai_tol=0.1, n_pc='auto', n_jobs=None, verbose=None, engine=None)

Fit the GEDAI model to the epochs.

Parameters:

epochsmne.BaseEpochs

The epochs to fit the model to.

picksstr | list | slice

Channels to include. Note that all channels selected must have the same type. Slices and lists of integers will be interpreted as channel indices. In lists, channel name strings (e.g. ['Fp1', 'Fp2']) will pick the given channels. Can also be the string values "all" to pick all channels, or "data" to pick data channels. The default is "eeg" to pick all EEG channels.

reference_covstr | mne.Covariance

The reference covariance to use. If 'leadfield', use a pre-computed covariance. The precomputed covariance if computed from a leadfield made using 1005 EEG channels layout and fsaverage head model. If mne.Covariance, use a pre-computed covariance. See compute_covariance_from_forward() for more details on how to compute a covariance from a forward solution.

sensai_methodstr

The method to use for threshold optimization. Can be 'optimize' (default, continuous scalar minimization) or 'gridsearch'.

noise_multiplierfloat | str

The noise multiplier or string preset for artefact threshold rejection optimization. Supported string presets:

• "auto" : Standard balance (noise_multiplier = 3.0, default).

• "auto+" : More aggressive denoising (noise_multiplier = 1.5).

• "auto-" : More conservative denoising (noise_multiplier = 6.0).

Alternatively, a custom numerical float can be passed.

sensai_boundstuple of float

The (min, max) bounds for the SENSAI search threshold. Default (-6.0, 12.0).

sensai_tolfloat

Absolute tolerance (xatol) for threshold optimization when sensai_method='optimize'. Defaults to 0.1 for fast convergence. Can be set to smaller values (e.g. 0.01) for finer search precision.

n_pcint | “auto”, default=”auto”

The number of principal components to retain for the SENSAI artifact template subspace similarity evaluation. If "auto" (default):

• For EEG: Automatically uses 3 principal components for rank-normalized 3D volumetric dipolar subspace similarity.

• For MEG: Automatically prescans the GEVD artifact eigenvalue spectrum to select 2 or 3 principal components adaptively depending on ambient room noise harmonics versus localized bursts.

If an int, uses the specified number of principal components.

n_jobsint | None

The number of jobs to run in parallel. If 1 or None (default), computations are run serially. If -1, all available CPU cores are used.

verboseint | str | bool | None

Control verbosity of the logging output. If None, use the default verbosity level ("INFO"). If a boolean, True corresponds to "INFO" and False corresponds to "WARNING". The default is None (interpreted as "INFO").

enginestr | None

Computation engine (‘numpy’, ‘torch’, or ‘auto’). If None, uses engine specified at initialization.

fit_raw(raw, picks='eeg', duration=1.0, overlap=0.5, reject_by_annotation=False, reference_cov='leadfield', sensai_method='optimize', noise_multiplier='auto', sensai_bounds=(-6.0, 12.0), sensai_tol=0.1, highpass_prefilter=0.1, n_pc='auto', n_jobs=None, verbose=None, engine=None)

Fit the GEDAI model to the raw data.

Parameters:

rawmne.io.BaseRaw

The raw data to fit the model to.

picksstr | list | slice

Channels to include. Note that all channels selected must have the same type. Slices and lists of integers will be interpreted as channel indices. In lists, channel name strings (e.g. ['Fp1', 'Fp2']) will pick the given channels. Can also be the string values "all" to pick all channels, or "data" to pick data channels. The default is "eeg" to pick all EEG channels.

durationfloat

Duration of each epoch in seconds. The default is 1.0.

overlapfloat

The overlap ratio between consecutive epochs, between 0 and 1. The default is 0.5 (50% overlap). For example, 0.5 means 50% overlap and 0.75 means 75% overlap.

reject_by_annotationbool

Whether annotated bad segments should be rejected. It is recommended to set this to False for fitting, since the algorithm needs to learn from bad segments. The default is False.

reference_covstr | mne.Covariance

The reference covariance to use. If 'leadfield', use a pre-computed covariance. The precomputed covariance if computed from a leadfield made using 1005 EEG channels layout and fsaverage head model. If mne.Covariance, use a pre-computed covariance. See compute_covariance_from_forward() for more details on how to compute a covariance from a forward solution.

sensai_methodstr

The method to use for threshold optimization. Can be 'optimize' (default, continuous scalar minimization) or 'gridsearch'.

noise_multiplierfloat | str

The noise multiplier or string preset for artefact threshold rejection optimization. Supported string presets:

• "auto" : Standard balance (noise_multiplier = 3.0, default).

• "auto+" : More aggressive denoising (noise_multiplier = 1.5).

• "auto-" : More conservative denoising (noise_multiplier = 6.0).

Alternatively, a custom numerical float can be passed.

sensai_boundstuple of float

The (min, max) bounds for the SENSAI search threshold. Default (-6.0, 12.0).

sensai_tolfloat

Absolute tolerance (xatol) for threshold optimization when sensai_method='optimize'. Defaults to 0.1 for fast convergence. Can be set to smaller values (e.g. 0.01) for finer search precision.

highpass_prefilterfloat | None

Wavelet high-pass pre-filtering cutoff frequency in Hz (default 0.1 Hz).

n_pcint | “auto”, default=”auto”

The number of principal components to retain for the SENSAI artifact template subspace similarity evaluation. If "auto" (default):

• For EEG: Automatically uses 3 principal components for rank-normalized 3D volumetric dipolar subspace similarity.

• For MEG: Automatically prescans the GEVD artifact eigenvalue spectrum to select 2 or 3 principal components adaptively depending on ambient room noise harmonics versus localized bursts.

If an int, uses the specified number of principal components.

n_jobsint | None

The number of jobs to run in parallel. If 1 or None (default), computations are run serially. If -1, all available CPU cores are used.

verboseint | str | bool | None

Control verbosity of the logging output. If None, use the default verbosity level ("INFO"). If a boolean, True corresponds to "INFO" and False corresponds to "WARNING". The default is None (interpreted as "INFO").

enginestr | None

Computation engine (‘numpy’, ‘torch’, or ‘auto’).

fit_summary()

Compatibility wrapper for the fitted-model summary.

Returns:

summary_strstr

Formatted ASCII summary table.

plot_fit()

Plot the fitting results.

Returns:

figslist of matplotlib.figure.Figure

The list of figures showing the fitting results.

plot_sensai(raw_before, raw_after=None, epoch_duration_sec=1.0, n_pc=3, show=True)

Plot SENSAI subspace similarity and manifold classification.

Replicates MATLAB’s SENSAI_visualization.m with side-by-side Before/After subspace projections, LDA decision boundary shading, and marginal KDE distributions.

Parameters:

raw_beforemne.io.BaseRaw

Original EEG recording before denoising.

raw_aftermne.io.BaseRaw | None

Cleaned EEG recording after denoising. If None, automatically computed.

epoch_duration_secfloat

Epoch duration in seconds (default 1.0s).

n_pcint

Number of principal components for SSI calculation (default 3 for EEG).

showbool

Whether to call plt.show() or return the figure.

Returns:

figmatplotlib.figure.Figure

The SENSAI visualization figure.

metricsdict

A dictionary containing the computed SENSAI and ENOVA metrics.

transform_epochs(epochs, n_jobs=None, verbose=None, engine=None)

Transform epochs data using the fitted model.

Parameters:

epochsmne.Epochs

The epochs to transform.

n_jobsint | None

The number of jobs to run in parallel. If 1 or None (default), computations are run serially. If -1, all available CPU cores are used.

verboseint | str | bool | None

Control verbosity of the logging output. If None, use the default verbosity level ("INFO"). If a boolean, True corresponds to "INFO" and False corresponds to "WARNING". The default is None (interpreted as "INFO").

enginestr | None

Computation engine (‘numpy’, ‘torch’, or ‘auto’). If None, uses the engine specified at initialization.

Returns:

epochs_transformedmne.Epochs

The transformed epochs.

transform_raw(raw, overlap=0.5, n_jobs=None, verbose=None, engine=None)

Transform raw data using the fitted model.

Parameters:

rawmne.io.BaseRaw

The raw data to fit the model to.

overlapfloat

The overlap ratio between consecutive epochs, between 0 and 1. The default is 0.5 (50%% overlap). For example, 0.5 means 50%% overlap and 0.75 means 75%% overlap.

n_jobsint | None

The number of jobs to run in parallel. If 1 or None (default), computations are run serially. If -1, all available CPU cores are used.

verboseint | str | bool | None

Control verbosity of the logging output. If None, use the default verbosity level ("INFO"). If a boolean, True corresponds to "INFO" and False corresponds to "WARNING". The default is None (interpreted as "INFO").

enginestr | None

Computation engine (‘numpy’, ‘torch’, or ‘auto’). If None, uses the engine specified at initialization.

Returns:

raw_transformedmne.io.BaseRaw

The transformed raw data.

property ch_names

Get the channel names used during fitting.

property summary

Formatted ASCII summary table of the model fitting metrics.

Returns:

summary_strstr

Formatted ASCII summary table.

property threshold

Get the eigenvalue threshold used for cleaning.