gedai.gedai.AdaptiveMultibandGedai🔗

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

Adaptive Multiband Generalized Eigenvalue De-Artifacting Instrument.

A extension of MultibandGedai that uses adaptive window lengths for each wavelet band to ensure wavelet decomposition has enough cycles for accurate decomposition.

See [1].

Note

Since different epoch lengths are used for each wavelet band, it is not possible to fit the model using Epochs. If you want to use epochs, consider using MultibandGedai instead, which uses fixed epoch lengths across all wavelet bands.

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.
cycles_per_waveletint: Minimum number of cycles targeted per wavelet band. Lower-frequency bands use longer epochs to satisfy this target. The default is 12.
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

`clear_cache`()	Clear cached intermediate representations to free memory.
`fit_raw`(raw[, picks, overlap, ...])	Fit the model to 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_raw`(raw[, overlap, n_jobs, ...])	Apply the Adaptive Multiband GEDAI transform to raw data.

References

clear_cache()🔗

Clear cached intermediate representations to free memory.

Returns:

selfAdaptiveMultibandGedai: The instance itself.

fit_raw(raw, picks='eeg', 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 model to 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.

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.

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_raw(raw, overlap=0.5, n_jobs=None, verbose=None, engine=None)🔗

Apply the Adaptive Multiband GEDAI transform to raw data.

Parameters:

rawmne.io.BaseRaw: The raw data to transform.
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).