mne-denoise 0.0.1

Denoising Source Separation (DSS) and ZapLine algorithms for MNE-Python.

mne-denoise

Advanced denoising algorithms for M/EEG data in MNE-Python.

mne-denoise provides powerful signal denoising techniques for the MNE-Python ecosystem, including Denoising Source Separation (DSS) and ZapLine algorithms. These methods excel at extracting signals of interest by exploiting data structure rather than just variance.

Features

DSS Module

• Linear DSS: Extract components based on reproducibility across trials or characteristic frequencies
• Iterative DSS: Powerful nonlinear separation for complex non-Gaussian sources
• 20+ Pluggable Denoisers: Spectral, temporal, periodic, and ICA-style bias functions
• Specialized Variants: TSR, SSVEP enhancement, narrowband oscillation extraction

ZapLine Module

• ZapLine: Efficient removal of power line noise (50/60 Hz) and harmonics
• ZapLine-plus: Fully adaptive mode with automatic frequency detection
• Per-chunk Processing: Handles non-stationary noise characteristics
• Quality Assurance: Built-in spectral checks to prevent over-cleaning

Integration

• MNE-Python: Works directly with Raw, Epochs, and Evoked objects or numpy arrays.
• Scikit-Learn API: Standard fit(), transform(), fit_transform() interface
• Visualization: Built-in plotting for components and cleaning results

Installation

From PyPI (recommended)

pip install mne-denoise

From source (development)

git clone https://github.com/mne-tools/mne-denoise.git
cd mne-denoise
pip install -e ".[dev]"

Quick Start

DSS: Enhancing Evoked Responses

DSS finds spatial filters that maximize the ratio of reproducible (evoked) to total power:

import mne
from mne_denoise.dss import DSS, AverageBias

# Load your epoched data
epochs = mne.read_epochs("sample-epo.fif")

# Create DSS with trial-average bias
dss = DSS(bias=AverageBias(), n_components=5)
dss.fit(epochs)

# Option 1: Extract source time courses
sources = dss.transform(epochs)

# Option 2: Reconstruct denoised sensor data
cleaned_epochs = dss.transform(epochs, return_type="epochs")

DSS: Extracting Oscillations

Isolate specific frequency bands (e.g., alpha rhythm):

from mne_denoise.dss import DSS, BandpassBias

# Create bandpass bias for alpha (8-12 Hz)
bias = BandpassBias(sfreq=epochs.info["sfreq"], freq=10, bandwidth=4)

dss = DSS(bias=bias, n_components=3)
alpha_sources = dss.fit_transform(epochs)

ZapLine: Removing Line Noise

Remove 50/60 Hz power line artifacts:

import mne
from mne_denoise.zapline import ZapLine

# Load continuous data
raw = mne.io.read_raw_fif("sample-raw.fif", preload=True)

# Standard mode: specify line frequency
zapline = ZapLine(sfreq=raw.info["sfreq"], line_freq=50.0)
cleaned_data = zapline.fit_transform(raw)

# Adaptive mode: automatic detection and per-chunk processing
zapline_plus = ZapLine(
    sfreq=raw.info["sfreq"],
    line_freq=None,  # Auto-detect
    adaptive=True,
)
cleaned = zapline_plus.fit_transform(raw)
print(f"Detected line frequency: {zapline_plus.detected_freq_} Hz")

Documentation

Full documentation is available at mne-tools.github.io/mne-denoise.

• Getting Started Guide
• API Reference
• Example Gallery

🏗️ Architecture

mne_denoise/
├── dss/                    # Denoising Source Separation
│   ├── linear.py           # Core DSS algorithm, DSS estimator
│   ├── nonlinear.py        # Iterative DSS, IterativeDSS estimator
│   ├── denoisers/          # 20+ pluggable bias functions
│   │   ├── spectral.py     # BandpassBias, LineNoiseBias
│   │   ├── temporal.py     # TimeShiftBias, SmoothingBias
│   │   ├── periodic.py     # CombFilterBias, PeakFilterBias
│   │   └── ...
│   └── variants/           # Pre-built applications
│       ├── tsr.py          # Time-Shift Repeatability
│       ├── ssvep.py        # SSVEP enhancement
│       └── narrowband.py   # Oscillation extraction
├── zapline/                # Line noise removal
│   ├── core.py             # ZapLine estimator
│   └── adaptive.py         # ZapLine-plus utilities
└── viz/                    # Visualization tools

Testing

# Run tests
pytest

# With coverage
pytest --cov=mne_denoise --cov-report=html

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Development setup
git clone https://github.com/<your-username>/mne-denoise.git
cd mne-denoise
pip install -e ".[dev,docs]"
pre-commit install

References

DSS

Särelä, J., & Valpola, H. (2005). Denoising source separation. Journal of Machine Learning Research, 6, 233-272.

de Cheveigné, A., & Simon, J. Z. (2008). Denoising based on spatial filtering. Journal of Neuroscience Methods, 171(2), 331-339.

ZapLine

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

Klug, M., & Kloosterman, N. A. (2022). Zapline-plus: A completely automatic and highly effective method for removing power line noise. Human Brain Mapping, 43(9), 2743-2758.

License

BSD 3-Clause License. See LICENSE for details.