mne_denoise.zapline.ZapLine#

class mne_denoise.zapline.ZapLine(sfreq: float, line_freq: float | None = 60.0, n_remove: 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, adaptive: bool = False, adaptive_params: dict | None = None)[source]#

ZapLine Transformer for line noise removal.

Implements the ZapLine algorithm [1] for removing power line noise (50/60 Hz) and its harmonics from M/EEG recordings. Inherits from DSS and is compatible with scikit-learn and MNE-Python objects.

The algorithm uses Denoising Source Separation (DSS) to find spatial filters that maximize power at the line noise frequency, then projects out these noise components while preserving neural signals.

The cleaning process follows these steps:

  1. Smoothing: Apply a moving average filter with period matching the line frequency to separate slowly-varying (“smooth”) and fast (“residual”) components

  2. DSS: Apply DSS to the residual using LineNoiseBias to find components that maximize line noise power

  3. Artifact removal: Project out the top noise components from the residual

  4. Reconstruction: Add back the smooth component to obtain cleaned data

Parameters:

  • sfreq (float) – Sampling frequency in Hz. Required.

  • line_freq (float | None, default=60.0) – Line noise frequency in Hz (typically 50 or 60 Hz). If None and adaptive=True, the frequency is auto-detected. If None and adaptive=False, raises an error.

  • n_remove (int | 'auto', default='auto') – Number of noise components to remove. If 'auto', uses iterative outlier removal on DSS eigenvalues [1]. If int, removes exactly that many components.

  • n_harmonics (int | None, default=None) – Number of harmonics to include in the bias function. If None, auto-determined based on Nyquist frequency.

  • nfft (int, default=1024) – FFT length for the spectral bias function.

  • nkeep (int | None, default=None) – Number of PCA components to retain before DSS. If None, uses rank or auto-determined from data.

  • rank (int | None, default=None) – Rank of the data for whitening. If None, auto-determined.

  • reg (float, default=1e-9) – Regularization parameter for DSS covariance inversion.

  • threshold (float, default=3.0) – Sigma threshold for iterative outlier removal when n_remove='auto'.

  • adaptive (bool, default=False) – If True, use adaptive ZapLine-plus mode [2] with: - Automatic frequency detection - Data segmentation based on covariance stationarity - Per-segment parameter adaptation

  • adaptive_params (dict | None, default=None) – Parameters for adaptive mode. See Notes for available options.

filters_#

Spatial filters (unmixing matrix) for the removed noise components.

Type:

ndarray, shape (n_removed, n_channels)

patterns_#

Spatial patterns (mixing matrix) for the removed noise components.

Type:

ndarray, shape (n_channels, n_removed)

eigenvalues_#

DSS eigenvalues (ratio of line-noise power to total power).

Type:

ndarray, shape (n_components,)

n_removed_#

Number of components actually removed.

Type:

int

n_harmonics_#

Number of harmonics used by the bias function.

Type:

int | None

adaptive_results_#

Results from adaptive mode, including chunk information.

Type:

dict | None

See also

DSS

Parent class implementing Denoising Source Separation.

LineNoiseBias

Bias function for line noise.

mne_denoise.zapline.adaptive

Adaptive ZapLine-plus utilities.

Notes

Adaptive Mode Parameters (adaptive_params dict):

  • fmin : float (default 17.0) - Minimum frequency for noise detection

  • fmax : float (default 99.0) - Maximum frequency for noise detection

  • process_harmonics : bool (default False) - Process detected harmonics

  • max_harmonics : int - Maximum number of harmonics to process

  • hybrid_fallback : bool (default False) - Use notch filter fallback

  • min_chunk_len : float (default 30.0) - Minimum segment length in seconds

  • n_remove_params : dict - Parameters for component selection

  • qa_params : dict - Parameters for QA (max_sigma, min_sigma)

Examples

Basic usage with MNE Raw object:

>>> from mne_denoise.zapline import ZapLine
>>> # Remove 50 Hz line noise
>>> zapline = ZapLine(sfreq=1000, line_freq=50.0)
>>> raw_clean = zapline.fit_transform(raw)

Using automatic component selection:

>>> zapline = ZapLine(sfreq=1000, line_freq=60.0, n_remove="auto")
>>> zapline.fit(data)
>>> print(f"Removed {zapline.n_removed_} components")
>>> cleaned = zapline.transform(data)

Adaptive mode (ZapLine-plus):

>>> zapline = ZapLine(sfreq=1000, line_freq=None, adaptive=True)
>>> cleaned = zapline.fit_transform(epochs)  # Auto-detects noise frequencies

References

[1] (1,2)

de Cheveigné, A. (2020). ZapLine: A simple and effective method to remove power line artifacts. NeuroImage, 207, 116356.

[2]

Klug, M., & Kloosterman, N. A. (2022). Zapline-plus: A Zapline extension for automatic and adaptive removal of frequency-specific noise artifacts in M/EEG. Human Brain Mapping, 43(9), 2743-2758.

__init__(sfreq: float, line_freq: float | None = 60.0, n_remove: 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, adaptive: bool = False, adaptive_params: dict | None = None)[source]#

Methods

__init__(sfreq[, line_freq, n_remove, ...])

fit(X[, y])

Fit ZapLine spatial filters to data.

fit_transform(X[, y])

Fit and transform data in one step.

get_metadata_routing()

Get metadata routing of this object.

get_normalized_patterns()

Get L2-normalized spatial patterns for visualization.

get_params([deep])

Get parameters for this estimator.

inverse_transform(sources[, component_indices])

Transform sources back to sensor space.

set_fit_request(*[, weights])

Configure whether metadata should be requested to be passed to the fit method.

set_inverse_transform_request(*[, ...])

Configure whether metadata should be requested to be passed to the inverse_transform method.

set_output(*[, transform])

Set output container.

set_params(**params)

Set the parameters of this estimator.

transform(X)

Apply ZapLine cleaning to remove line noise.