gedai.gedai.MultibandGedai🔗

class gedai.gedai.MultibandGedai(wavelet_type='haar', wavelet_level='auto', broadband_pass=True, engine='auto')🔗

Multiband Generalized Eigenvalue De-Artifacting Instrument.

A multiband extension of the standard Gedai that applies GEDAI algorithm separately to different frequency bands (via wavelet decomposition). This approach allows for more targeted artifact removal while preserving neural signals. See [1].

Warning

For EEG channels, Gedai will set average reference internally to match the leadfield covariance reference. Gedai will not modify the input data in-place, but will create copies when necessary to ensure the original data remains unchanged.

Parameters:
wavelet_typestr

Wavelet to use for the decomposition. The default is 'haar'. See pywt.wavedec() for the list of available wavelets.

wavelet_levelint or ‘auto’

The wavelet decomposition level. If ‘auto’, automatically computed from sfreq.

broadband_passbool

Whether to run an initial broadband GED pass before multiband wavelet decomposition.

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.

wavelet_level

Wavelet level (integer level if fitted, or configured setting).

Methods

fit_epochs(epochs[, picks, reference_cov, ...])

Fit the GEDAI model to the epochs data.

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

fit_epochs(epochs, picks='eeg', reference_cov='leadfield', sensai_method='optimize', noise_multiplier='auto', sensai_tol=0.1, wavelet_low_cutoff=0.5, n_pc='auto', n_jobs=None, verbose=None, engine=None)🔗

Fit the GEDAI model to the epochs data.

Parameters:
epochsmne.Epochs

The epochs 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.

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

wavelet_low_cutofffloat | None

If a float is provided, zero out all wavelet levels whose upper frequency bound is below this cutoff frequency in Hz. If None, no frequency band is zeroed out. If "auto", the cutoff is automatically determined based on the info[‘highpass’] value (minimum 0.5 Hz). While reading data from a file, info[‘highpass’] might be missing (i.e., equal to 0.0). If you know that your data has been high-pass filtered, make sure to set wavelet_low_cutoff to the high-pass cutoff frequency. The default is 0.5.

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 the 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_tol=0.1, wavelet_low_cutoff=0.5, 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_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.

wavelet_low_cutofffloat | None

If a float is provided, zero out all wavelet levels whose upper frequency bound is below this cutoff frequency in Hz. If None, no frequency band is zeroed out. If "auto", the cutoff is automatically determined based on the info[‘highpass’] value (minimum 0.5 Hz). While reading data from a file, info[‘highpass’] might be missing (i.e., equal to 0.0). If you know that your data has been high-pass filtered, make sure to set wavelet_low_cutoff to the high-pass cutoff frequency. The default is 0.5.

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 the engine specified at initialization.

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

A list of figures showing the fitting results for each wavelet band that was not ignored.

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.

Returns:
ch_nameslist of str

The channel names that were used during model fitting.

property summary🔗

Formatted ASCII summary table of the model fitting metrics.

Returns:
summary_strstr

Formatted ASCII summary table.

property wavelet_level🔗

Wavelet level (integer level if fitted, or configured setting).