mne_denoise.zapline.ZapLine#

class mne_denoise.zapline.ZapLine(sfreq: float, line_freq: float | None = 60.0, n_select: int | str = 'auto', n_harmonics: int | None = None, nfft: int = 1024, nkeep: int | None = None, rank: int | None = None, reg: float = 1e-09, threshold: float = 3.0, knee_rel_floor: float = 0.01, knee_min_ratio: float = 3.0, adaptive: bool = False, adaptive_params: dict | None = None, segmenter=None, crossfade: float = 0.0, whiten: bool = False, noise_cov=None, verbose: bool | str | int | None = None)[source]#

DSS-based line-noise removal estimator.

ZapLine fits spatial filters for a line frequency and removes selected components. Adaptive mode performs the ZapLine-plus frequency, segmentation, and per-segment processing path.

Parameters:

sfreqfloat: Sampling frequency in Hz.
line_freqfloat or None, default=60.0: Fundamental line frequency in Hz. Required in standard mode; None enables detection in adaptive mode.
n_selectint or {“auto”}, default=”auto”: Number of DSS components to remove, or automatic selection.
n_harmonicsint or None, default=None: Number of harmonics; None uses harmonics below Nyquist.
nfftint, default=1024: FFT length for the line-noise bias.
nkeepint or None, default=None: Number of dimensions retained before DSS.
rankint or None, default=None: Whitening rank.
regfloat, default=1e-9: DSS covariance regularization.
thresholdfloat, default=3.0: Outlier threshold for automatic component selection.
knee_rel_floorfloat, default=0.01: Relative score floor for knee selection.
knee_min_ratiofloat, default=3.0: Minimum score ratio for knee selection.
adaptivebool, default=False: Use adaptive ZapLine-plus processing.
adaptive_paramsdict or None, default=None: Parameters for adaptive frequency detection and segment processing.
segmenterobject or None, default=None: Segmenter used in adaptive mode.
crossfadefloat, default=0.0: Boundary crossfade duration in seconds in adaptive mode.
whitenbool, default=False: Pre-whiten supported MNE data channels before processing.
noise_covmne.Covariance or None, default=None: Noise covariance used when whiten=True.
verbosebool, str, int, or None, default=None: Logging level.

Attributes:

filters_, patterns_, eigenvalues_: Fitted DSS filters, patterns, and eigenvalues.
n_removed_int: Number of removed components or adaptive component passes.
n_harmonics_int or None: Number of harmonics used by the bias.
adaptive_results_dict or None: Diagnostics from adaptive processing.

See also

mne_denoise.spectrum_interpolation.SpectrumInterpolation: Spectral-amplitude interpolation around line frequencies.
mne_denoise.dss.DSS: General DSS estimator underlying standard ZapLine decomposition.

Notes

Standard fit followed by transform uses a fitted operator. Adaptive mode requires fit_transform because fitting and cleaning are performed per segment. The adaptive workflow follows the ZapLine and ZapLine-plus methods [1][2].

References

Examples

>>> import numpy as np
>>> from mne_denoise.zapline import ZapLine
>>> rng = np.random.default_rng(0)
>>> data = rng.standard_normal((8, 2000))
>>> model = ZapLine(sfreq=1000.0, line_freq=50.0, n_select="auto")
>>> clean = model.fit_transform(data)

fit(X, y=None, *, verbose: bool | str | int | None = None)[source]#

Fit standard-mode ZapLine filters.

Parameters:

XRaw, Epochs, Evoked, or ndarray: Data used to fit the filters.
yNone, default=None: Ignored for scikit-learn compatibility.
verbosebool, str, int, or None, default=None: Logging level.

Returns:

ZapLine: The fitted estimator.

Raises:

RuntimeError: If adaptive=True; use fit_transform instead.

fit_transform(X, y=None, *, callback=None, verbose: bool | str | int | None = None, **fit_params)[source]#

Fit and transform with standard or adaptive ZapLine.

Parameters:

XRaw, Epochs, Evoked, or ndarray: Data to clean.
yNone, default=None: Ignored for scikit-learn compatibility.
callbackcallable or None, default=None: Synchronous progress callback in adaptive mode.
verbosebool, str, int, or None, default=None: Logging level.
**fit_paramsdict: Additional parameters passed to the standard DSS fit_transform path.

Returns:

same type as X: Cleaned data with the input layout.

transform(X, *, verbose: bool | str | int | None = None)[source]#

Apply fitted standard-mode ZapLine filters.

Parameters:

XRaw, Epochs, Evoked, or ndarray: Data with the fitted channel layout.
verbosebool, str, int, or None, default=None: Logging level.

Returns:

same type as X: Cleaned data.

Raises:

RuntimeError: If adaptive=True or the estimator is not fitted.