mne_rt.tools.AdaptiveMultibandGEDAIDenoiser#

class mne_rt.tools.AdaptiveMultibandGEDAIDenoiser(n_channels: int, sfreq: float, wavelet_level: int | str = 'auto', cycles_per_wavelet: int = 6, shrinkage: float = 0.05, filter_order: int | None = None, n_jobs: int = 1, wavelet_low_cutoff: float = 0.5, broadband_pass: bool = True, prefilter_mode: Literal['reference', 'lowcut', 'none'] = 'reference')[source]#

Bases: object

Streaming adaptive multiband GEDAI.

Parameters:

n_channelsint: Number of EEG channels. SENSAI calibration here uses the EEG objective only; gedai’s MEG objective is not implemented, and fit_gedai() refuses multiband mode for MEG.
sfreqfloat: Sampling frequency in Hz.
wavelet_levelint | “auto”, default “auto”: Number of wavelet decomposition levels (n_bands = wavelet_level + 1). If "auto", uses gedai.wavelet.transform.compute_wavelet_level().
cycles_per_waveletint, default 6: Cycles at each band’s lower frequency used to size covariance epochs. The lowest approximation uses half its upper edge, as in pyGEDAI.
shrinkagefloat, default 0.05: Reference covariance shrinkage: (1-s) * R + s * mean(diag(R)) * I.
filter_orderint | None, default None: Deprecated compatibility argument. Haar kernels have no Butterworth order. Passing this argument logs a warning; it has no effect.
n_jobsint, default 1: Number of threads used to denoise bands in parallel (joblib, prefer="threads"). Use -1 for all cores.
wavelet_low_cutofffloat, default 0.5: Bands whose upper edge is at or below this frequency (Hz) are discarded. This is a dyadic wavelet cutoff, not a brick-wall filter. Also controls the broadband prefilter and automatic level selection.
broadband_passbool, default True: Calibrate and apply a broadband GEDAI pass before wavelet cleaning, matching pyGEDAI’s default. The broadband covariance epoch is one second (or enough samples for the channel count).
prefilter_mode{“reference”, “lowcut”, “none”}, default “reference”: "reference" preserves the pyGEDAI prefilter cascade. "lowcut" uses only one Haar highpass at wavelet_low_cutoff, even without a broadband pass. "none" skips standalone prefilters; sub-cutoff wavelet bands are still excluded. The latter modes reduce delay but change calibration and broadband cleaning, so require a new fit.

Notes

fit calibrates an eigenvalue threshold in each band with pyGEDAI’s EEG SENSAI objective (up to three reference principal components, noise weight 3, frequency-dependent sensitivity bounds). The fitted sensitivity stays fixed; each local eigenvalue spectrum determines the current cutoff. Baseline and live data must use the same units and sensor reference as the supplied leadfield.

The finite trailing covariance history is bounded by the pyGEDAI epoch size, not an EMA with an unbounded tail. All emitted samples lag their input timestamps by latency seconds, excluding computation time. This can be several seconds even though no acquisition chunks are held waiting for a processing window. Offline calibration may use future samples within the baseline, but live filtering never reads future chunks.

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

__init__(n_channels: int, sfreq: float, wavelet_level: int | str = 'auto', cycles_per_wavelet: int = 6, shrinkage: float = 0.05, filter_order: int | None = None, n_jobs: int = 1, wavelet_low_cutoff: float = 0.5, broadband_pass: bool = True, prefilter_mode: Literal['reference', 'lowcut', 'none'] = 'reference') → None[source]#

Methods

`__init__`(n_channels, sfreq[, wavelet_level, ...])
`fit`(data[, leadfield])	Fit per-band spatial filters from baseline data.
`update_and_denoise`(data[, template_map, ...])	Denoise one real-time chunk, updating per-band covariances as it goes.

Attributes

`activation_patterns`	Activation patterns `A` per band, each shape (n_channels, n_channels).
`band_frequencies`	List of `(fmin, fmax)` per band.
`band_time_constants`	Trailing covariance epoch durations (seconds), including ignored bands.
`current_eigenvalue_thresholds`	Most recently used per-band automatic cutoffs.
`delay_samples`	Align emitted sample `t` to source sample `t - delay_samples`.
`eigenvalue_thresholds`	Baseline SENSAI eigenvalue cutoffs; live cutoffs adapt to each spectrum.
`eigenvalues`	Sorted eigenvalues (descending) per band.
`latency`	Fixed FIR reconstruction delay in seconds; not compute time.
`n_bands`	Number of frequency bands.
`retained_bands`	Whether each band contributes to the reconstruction.
`spatial_filters`	Spatial filters `W` per band, each shape (n_channels, n_channels).

fit(data: ndarray, leadfield: ndarray | None = None) → AdaptiveMultibandGEDAIDenoiser[source]#

Fit per-band spatial filters from baseline data.

Parameters:

datandarray, shape (n_channels, n_samples): Broadband baseline recording.
leadfieldndarray, shape (n_channels, n_sources), optional: Forward/leadfield gain matrix. If given, the reference covariance is L @ L.T (true GEDAI / leadfield mode); otherwise the broadband covariance of data is used (band-filter mode). For automatic selection without a leadfield, this baseline must be representative of the signal covariance to preserve.

Returns:

self

update_and_denoise(data: ndarray, template_map: ndarray | None = None, threshold: float = 0.7, n_artifact: int | str = 'auto', update_covariance: bool = True, refit: bool = True) → ndarray[source]#

Denoise one real-time chunk, updating per-band covariances as it goes.

Parameters:

datandarray, shape (n_channels, n_samples): New chunk of broadband sensor data.
template_mapndarray, shape (n_channels,), optional: Known artifact topography (e.g. blink). If given, components whose activation pattern correlates with it above threshold (absolute correlation) are suppressed in every band.
thresholdfloat, default 0.7: Absolute-correlation threshold used with template_map.
n_artifactint | “auto”, default “auto”: When template_map is None, "auto" rejects eigenvalues above each band’s current SENSAI threshold, calculated from the baseline-fitted sensitivity and the local eigenvalue spectrum. With no leadfield, the baseline broadband covariance is the signal reference instead of a theoretical brain model. An integer overrides SENSAI with a fixed count. Leadfield mode suppresses the largest eigenvalues (excess power relative to the brain model); band-filter mode suppresses the smallest (least band-specific). Zero disables component rejection, not prefiltering, output delay, or sub-cutoff band removal. A positive fixed count can remove activity from clean recordings.
update_covariancebool, default True: Whether to update each band’s trailing-epoch covariance with this chunk.
refitbool, default True: Whether to re-solve the GED for each band after updating its covariance. Set to False to only update covariances (e.g. to re-solve less often than every chunk) while still denoising with the previous spatial filters.

Returns:

data_cleanndarray, shape (n_channels, n_samples): Output sample t corresponds to input sample t - delay_samples, including delayed calibration history at startup.

property n_bands: int#: Number of frequency bands.

property band_frequencies: list[tuple[float, float]]#: List of (fmin, fmax) per band.

property band_time_constants: list[float]#: Trailing covariance epoch durations (seconds), including ignored bands.

property retained_bands: list[bool]#: Whether each band contributes to the reconstruction.

property latency: float#: Fixed FIR reconstruction delay in seconds; not compute time.

property delay_samples: int#: Align emitted sample t to source sample t - delay_samples.

property eigenvalues: list[ndarray]#: Sorted eigenvalues (descending) per band.

property eigenvalue_thresholds: list[float]#: Baseline SENSAI eigenvalue cutoffs; live cutoffs adapt to each spectrum.

property current_eigenvalue_thresholds: list[float]#: Most recently used per-band automatic cutoffs.

property spatial_filters: list[ndarray]#: Spatial filters W per band, each shape (n_channels, n_channels).

property activation_patterns: list[ndarray]#: Activation patterns A per band, each shape (n_channels, n_channels).