π§ Advanced Python library for automatic and adaptive removal of line noise from EEG data
PyZaplinePlus is a professional Python adaptation of the Zapline-plus library, designed to automatically remove spectral peaks like line noise from EEG data while preserving the integrity of the non-noise spectrum and maintaining the data rank. Unlike traditional notch filters, PyZaplinePlus uses sophisticated spectral detection and Denoising Source Separation (DSS) to identify and remove line noise components adaptively.
EEG signals often suffer from line noise contamination, typically from power lines (e.g., 50 Hz or 60 Hz), and other artifacts. PyZaplinePlus is an adaptive noise removal tool that uses sophisticated spectral detection and denoising source separation (DSS) to identify and remove these line components, providing clean EEG signals without unnecessary loss of important information.
The main objectives of PyZaplinePlus include:
- Accurate and adaptive removal of line noise at specified frequencies.
- Support for automatic noise frequency detection within a given range.
- Methods for handling flat channels, adaptive chunk segmentation, and detailed evaluation of the cleaning process.
- Line Noise Detection: Automatic detection of line noise frequencies (50 Hz, 60 Hz, or user-specified) to ensure optimal performance in different environments.
- Adaptive Chunk Segmentation: The signal can be segmented using either fixed-length or adaptive chunks, enhancing the precision of noise removal.
- Denoising Source Separation (DSS): Uses DSS combined with PCA to identify and remove noise components, reducing interference while maintaining data integrity.
- Advanced Spectrum Analysis: Refined detection mechanisms for identifying noisy components in both the coarse and fine frequency domains.
- Visualization Support: Built-in functionality for plotting power spectra before and after denoising to allow easy evaluation of noise removal results.
pip install pyzaplineplus
git clone https://github.com/snesmaeili/PyZapline_plus.git
cd PyZapline_plus
pip install -e ".[dev]"
# For MNE-Python integration
pip install pyzaplineplus[mne]
# For development
pip install pyzaplineplus[dev]
- Python: 3.8 or higher
- Core dependencies:
numpy >= 1.20.0
scipy >= 1.7.0
scikit-learn >= 1.0.0
matplotlib >= 3.3.0
- Optional:
mne >= 1.0.0
(for EEG integration)
import numpy as np
from pyzaplineplus import zapline_plus
# Your EEG data (time Γ channels)
data = np.random.randn(10000, 64) # 10s of 64-channel data at 1000 Hz
sampling_rate = 1000
# Clean the data
cleaned_data, config, analytics, plots = zapline_plus(data, sampling_rate)
# Optional: inspect analytics keys
print('Analytics keys:', list(analytics.keys()))
# Figures (if plotResults=True) are saved under ./figures/
from pyzaplineplus import PyZaplinePlus
# Initialize with custom parameters
zp = PyZaplinePlus(
data, sampling_rate,
noisefreqs=[50, 60], # Target 50 and 60 Hz
minfreq=45, # Search range: 45-65 Hz
maxfreq=65,
chunkLength=10, # 10-second chunks
adaptiveNremove=True, # Adaptive component removal
plotResults=True # Generate diagnostic plots
)
# Run the cleaning process
clean_data, config, analytics, plots = zp.run()
import mne
from pyzaplineplus import zapline_plus
# Load your MNE data
raw = mne.io.read_raw_fif('sample_raw.fif', preload=True)
data = raw.get_data().T # Transpose to time Γ channels
sampling_rate = raw.info['sfreq']
# Clean the data
cleaned_data, _, _, _ = zapline_plus(data, sampling_rate)
# Update your MNE object
raw._data = cleaned_data.T
import numpy as np
from pyzaplineplus import zapline_plus
# Simulate realistic EEG data with line noise
fs = 500 # Sampling rate
duration = 30 # seconds
n_channels = 64
# Create base EEG signal
t = np.arange(0, duration, 1/fs)
eeg = np.random.randn(len(t), n_channels) * 10 # ΞΌV
# Add 50 Hz line noise
line_noise = 5 * np.sin(2 * np.pi * 50 * t)
noisy_eeg = eeg + line_noise[:, np.newaxis]
# Remove line noise
clean_eeg, config, analytics, plots = zapline_plus(
noisy_eeg, fs,
noisefreqs='line', # Automatic detection
plotResults=True
)
print(f"Noise reduction: {analytics['noise_freq_50']['proportion_removed_noise']*100:.1f}%")
data
: EEG signal data, with dimensions (time, channels).sampling_rate
: Sampling frequency of the EEG data.noisefreqs
: Frequencies of noise to be removed, or set to'line'
to automatically detect line noise.- Additional parameters (keyword arguments) to fine-tune the algorithm include:
minfreq
,maxfreq
: Frequency range to search for noise.adaptiveNremove
: Whether to use adaptive DSS component removal.chunkLength
: Length of chunks for fixed segmentation (in seconds).segmentLength
: Length of segments for adaptive chunk segmentation.plotResults
: Boolean to enable or disable result visualization.
The run()
method returns the following:
clean_data
: The denoised EEG data.config
: The configuration used during processing.analytics
: Metrics and statistics evaluating the effectiveness of noise removal.plots
: Handles to the generated figures, ifplotResults=True
.
PyZaplinePlus provides both coarse and fine detection methods for line noise. The initial spectrum is analyzed to detect strong line noise candidates, and a refined frequency search is conducted to locate the noise peaks more accurately.
The core of the noise removal process utilizes DSS with Principal Component Analysis (PCA) to isolate noisy components and remove them selectively. This method ensures minimal alteration of the original signal, maintaining as much of the non-noise-related brain activity as possible.
The cleaning process includes an adaptive mechanism that adjusts based on how successful the noise removal was. If the algorithm detects insufficient cleaning, it iteratively refines the parameters to ensure effective denoising.
PyZaplinePlus can plot the power spectra of the original and cleaned data, providing an overview of the changes and confirming the effectiveness of the cleaning. It also computes analytical metrics such as noise power reduction to quantify performance.
- EEG Signal Processing: PyZaplinePlus is especially well-suited for preprocessing EEG signals collected in environments where power line noise is present.
- BCI Research: Brain-computer interface studies that require real-time or offline EEG data analysis can leverage PyZaplinePlus for high-quality signal preprocessing.
- General Biomedical Signal Denoising: PyZaplinePlus can also be applied to other physiological signals, such as ECG or EMG, for noise suppression.
We welcome contributions! Please see our Contributing Guide for details on:
- Development setup
- Coding standards
- Testing requirements
- Pull request process
Quick start for contributors:
git clone https://github.com/SinaEsmaeili/PyZaplinePlus.git
cd PyZaplinePlus
pip install -e ".[dev]"
pytest # Run tests
PyZaplinePlus is released under the MIT License. See LICENSE
for more details.
The PyZaplinePlus algorithm is inspired by the MATLAB-based Zapline-plus implementation, initially designed for removing line noise from EEG signals. Special thanks to the original authors and contributors who laid the foundation for this adaptive noise removal approach.
For full documentation, examples, and API reference, visit:
- Full docs: https://snesmaeili.github.io/PyZapline_plus/
- Examples: https://snesmaeili.github.io/PyZapline_plus/user-guide/examples/
- API: https://snesmaeili.github.io/PyZapline_plus/api/
If you find PyZaplinePlus useful in your research, please cite the original papers:
- 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, 1β16. https://doi.org/10.1002/hbm.25832
- de Cheveigne, A. (2020). ZapLine: a simple and effective method to remove power line artifacts. NeuroImage, 1, 1-13. https://doi.org/10.1016/j.neuroimage.2019.116356
- π Documentation: https://snesmaeili.github.io/PyZapline_plus/
- π Issues: https://github.com/snesmaeili/PyZapline_plus/issues
- π¬ Discussions: https://github.com/snesmaeili/PyZapline_plus/discussions
- π§ Email: sina.esmaeili@umontreal.ca
- MNE-Python: Comprehensive neurophysiological data analysis
- EEGLAB: MATLAB toolbox for EEG analysis
- FieldTrip: Advanced analysis of MEG, EEG, and invasive electrophysiological data