Adaptive line-noise removal (“Zapline+”) for MNE (core mne.preprocessing.zapline)

[snesmaeili]

Describe the new feature or enhancement

What

Add an adaptive, component-based line-noise remover to the MNE ecosystem, based on the Zapline-plus method (Klug & Kloosterman, 2022) implemented in clean-room MIT Python. The method can:
- auto-detects narrowband peaks at power-line frequency and harmonics (50/60 Hz; handles slow drift),
- chunks the data by spatial stability to handle non-stationarity,
- removes the minimal number of DSS/PCA components needed per peak,
- aims to preserve rank and minimize broadband distortion.

Why

mne.filter.notch_filter is robust but fixed-frequency; repeated or wide notches can cause spectral collateral damage and may alter rank when interference drifts or changes spatially (common in MoBI/mobile EEG and some MEG/iEEG/LFP). An adaptive approach reduces narrowband artifacts while protecting broadband content.

Paper.
MATLAB refrence: MariusKlug/zapline-plus.
My Python library (MIT): PyZapline_plus.

Describe your proposed implementation

Implement an adaptive, component-based line-noise remover as a new public function in mne.preprocessing, with an optional thin Raw/Epochs/Evoked method wrapper. The function mirrors MNE APIs (inst, picks, copy, verbose) and returns the cleaned instance (plus optional diagnostics) while preserving info, annotations, events, and rank.
The proposed public API looks like this :

mne.preprocessing.zapline(
    inst,
    picks="eeg",
    freqs="line",             # "line" => auto-detect 50/60 Hz (+ harmonics) with drift
    n_remove="auto",          # int | "auto" | list[int] per harmonic
    chunk_dur=None,           # seconds | "auto"; handles non-stationarity
    dss="auto",               # "auto" | dict (DSS/PCA config)
    guard=1.0,                # Hz around each peak to protect
    n_jobs=None,
    random_state=None,
    return_info=False,
    copy=True,
    verbose=None,
)

Algorithm

1. Peak detection

   • Compute a robust PSD aggregated across picks (e.g., median of channel PSDs via Welch).
   • If freqs="line", locate the dominant peak in 45–65 Hz, snap to 50 or 60 Hz, then generate harmonics < sfreq/2.
   • If freqs is float/list, use provided peaks directly.
   • Apply a guard band (±guard Hz) around each peak to quantify pre/post power and to avoid over-cleaning.

2. Chunking for non-stationarity

   • If chunk_dur is None/"auto", segment the data where spatial patterns are stable (e.g., windowed channel-covariance similarity; minimum length enforced).
   • If chunk_dur is a float, segment by duration. Chunk edges are cross-faded to avoid discontinuities.

3. Component selection & removal (per chunk × harmonic)

• Build a DSS/PCA transform emphasizing narrowband energy around the target peak (whitened data + band-focused criterion).
• Rank components by narrowband-to-broadband ratio (z-score).
• n_remove="auto" chooses the minimal number of components whose cumulative removal reduces the peak below a conservative threshold; otherwise use the user-given n_remove.
• Remove selected components and invert the transform to reconstruct the cleaned chunk.

4. Stitch & finalize

• Concatenate chunks with cross-fades if needed; preserve inst.info, bads, annotations, projections, and event timing.
• Compute diagnostics (pre/post PSD at peaks, components removed, chunk map).

Describe possible alternatives

From an API perspective, there are two packaging alternatives. One is to keep this as an official extension (e.g., mne-zapline). That gives faster releases and iteration but lives outside core. The other is to augment notch_filter with auto-peak detection; although convenient, it would mix fundamentally different concepts (filtering vs. spatial decomposition) and make diagnostics harder to expose. A dedicated mne.preprocessing.zapline function (or a thin apply_zapline method) keeps behavior clear and discoverable, surfaces diagnostics (peaks found, chunks, components removed, before/after PSD), and aligns with MNE’s preprocessing style.

Additional context

I have already implemented the method in Python as a clean-room library, PyZapline_plus (MIT), available here: PyZapline_plus
. The implementation follows the algorithmic ideas from Zapline-plus (Klug & Kloosterman, 2022)
I’m happy to adapt naming, defaults, thresholds, diagnostics, and API shape to match MNE conventions, and to refactor internals to meet core standards (docstrings, tests, tutorial, “What’s new”). I’m also open to either path—starting as an official extension (mne-zapline) or merging directly into core under mne.preprocessing—and I will revise the code based on maintainer feedback in this issue. If needed for a core merge, I’m willing to relicense my contribution under BSD-3 to align with MNE-Python. For reviewers’ convenience, I attached before/after PSD screenshots, a short synthetic benchmark notebook, and links to small test fixtures demonstrating peak detection, chunking for non-stationarity, and minimal DSS/PCA component removal.

[drammock]

xref to a discussion in #7170 about this. I've not studied the implementation of zapline, but from that discussion it sounds like it has at least some overlap with DSS, and there's suggestion in that thread that implementing DSS first, zapline second would make sense. @snesmaeili what is your opinion on that?

Regardless, thanks for the offer; I'll add it to the agenda of our next steering council meeting, and get back to you.

[snesmaeili]

Re #7170 and the DSS pointer: we’re aligned on DSS as the underlying method. My package uses the same DSS principle but wraps it in the full Zapline-plus pipeline (auto peak-finding, adaptive component count, and chunking for non-stationarity). By contrast, meegkit.dss_line is the original ZapLine helper (user-specified line frequency, fixed nremove, optional iterate). I can also make a separate DSS helper

[drammock]

Hi @snesmaeili. We discussed your proposal at the steering council meeting last friday. Here's a summary of that discussion:

• We think it makes the most sense to keep this as a separate package and are willing to host it within the mne-tools organization (and give you appropriate permissions to maintain it)
• We think it would be great to include a public-facing API to DSS in that package
• We're unsure about how to name it: if it has APIs for zapline(plus) and also DSS (and perhaps related algorithms in future?) calling it "mne-zapline" might not be the best name. We didn't have much time to brainstorm, so feel free to make suggestions if you have naming ideas. It's not hugely consequential, but it does need to get decided early in order to create the repo.
• We noticed that CursorAgent contributed to the existing codebase. We haven't managed to articulate this policy publicly yet, but FYI the steering council is of the unanimous opinion that at present, incorporating LLM-generated contributions is incompatible with respect for software licenses. Since LLMs may generate code that is "strikingly similar" to their training data, and it's been shown that most LLM training data is not constrained to MIT-0 or similarly non-attribution-requiring licenses, we conclude that incorporating LLM-generated code into any project likely violates the license of the code the LLM was trained on (note that both BSD 3-clause and MIT licenses require attribution via including the copyright notice, which includes a name or names). Therefore, we would need you to back out the above-linked commit that was co-authored by CursorAgent, and recreate that commit without AI assistance.

Does all that sound OK to you?