Metadata-Version: 2.4
Name: mne-denoise
Version: 0.0.1
Summary: Denoising Source Separation (DSS) and ZapLine algorithms for MNE-Python.
Author-email: Sina Esmaeili <sina.esmaeili@umontreal.ca>, Hamza Abdelhedi <hamza.abdelhedi@umontreal.ca>
Maintainer-email: Sina Esmaeili <sina.esmaeili@umontreal.ca>, Hamza Abdelhedi <hamza.abdelhedi@umontreal.ca>
License: BSD 3-Clause License
        
        Copyright (c) 2024-2025, Sina Esmaeili, Hamza Abdelhedi
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from this
           software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/mne-tools/mne-denoise
Project-URL: Documentation, https://mne-tools.github.io/mne-denoise/
Project-URL: Repository, https://github.com/mne-tools/mne-denoise
Project-URL: Issues, https://github.com/mne-tools/mne-denoise/issues
Project-URL: Changelog, https://github.com/mne-tools/mne-denoise/blob/main/CHANGELOG.md
Keywords: mne,eeg,meg,denoising,dss,zapline,neuroscience,electrophysiology,signal-processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mne>=1.0
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.8
Requires-Dist: matplotlib>=3.5
Requires-Dist: scikit-learn>=1.1
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-cov>=4.1.0; extra == "test"
Requires-Dist: pytest-timeout>=2.2.0; extra == "test"
Provides-Extra: dev
Requires-Dist: mne-denoise[test]; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Provides-Extra: docs
Requires-Dist: mne>=1.0; extra == "docs"
Requires-Dist: numpydoc>=1.6.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15.2; extra == "docs"
Requires-Dist: sphinx>=7.2.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Requires-Dist: sphinx-design>=0.5.0; extra == "docs"
Requires-Dist: sphinx-gallery>=0.15.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: mne-denoise[dev,docs]; extra == "all"
Dynamic: license-file

# mne-denoise

[![CI](https://github.com/mne-tools/mne-denoise/actions/workflows/ci.yml/badge.svg)](https://github.com/mne-tools/mne-denoise/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/mne-tools/mne-denoise/branch/main/graph/badge.svg)](https://codecov.io/gh/mne-tools/mne-denoise)
[![PyPI version](https://img.shields.io/pypi/v/mne-denoise.svg)](https://pypi.org/project/mne-denoise/)
[![Python versions](https://img.shields.io/pypi/pyversions/mne-denoise.svg)](https://pypi.org/project/mne-denoise/)
[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://mne-tools.github.io/mne-denoise/)
[![Downloads](https://pepy.tech/badge/mne-denoise)](https://pepy.tech/project/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)

```bash
pip install mne-denoise
```

### From source (development)

```bash
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:

```python
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):

```python
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:

```python
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](https://mne-tools.github.io/mne-denoise/)**.

- [Getting Started Guide](https://mne-tools.github.io/mne-denoise/getting-started.html)
- [API Reference](https://mne-tools.github.io/mne-denoise/api.html)
- [Example Gallery](https://mne-tools.github.io/mne-denoise/auto_examples/index.html)

## 🏗️ 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

```bash
# Run tests
pytest

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

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# 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](LICENSE) for details.
