Metadata-Version: 2.4
Name: mne-rt
Version: 1.0.0
Summary: MNE-RT — real-time M/EEG signal processing and analysis
Author-email: "Payam S. Shabestari" <payam.sadeghi74@gmail.com>
Maintainer-email: "Payam S. Shabestari" <payam.sadeghi74@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/payamsash/mne-rt
Project-URL: Documentation, https://payamsash.github.io/mne-rt/
Project-URL: Repository, https://github.com/payamsash/mne-rt
Project-URL: Bug Tracker, https://github.com/payamsash/mne-rt/issues
Keywords: neurofeedback,EEG,MEG,brain-computer interface,real-time,LSL,source localisation,signal processing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mne>=1.8
Requires-Dist: mne-lsl>=1.7
Requires-Dist: mne-connectivity>=0.7
Requires-Dist: mne-features>=0.3
Requires-Dist: mne-icalabel>=0.5
Requires-Dist: numpy<3,>=2.0
Requires-Dist: scipy>=1.13
Requires-Dist: matplotlib>=3.9
Requires-Dist: nibabel>=5.0
Requires-Dist: PyQt6>=6.7
Requires-Dist: pyqtgraph>=0.13
Requires-Dist: qtpy>=2.4
Requires-Dist: pyserial>=3.0
Requires-Dist: fooof>=1.0
Requires-Dist: pyunlocbox>=0.5.2
Requires-Dist: pactools>=0.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-osc>=1.8
Requires-Dist: imageio[ffmpeg]>=2.28
Provides-Extra: viz
Requires-Dist: pyvista>=0.44; extra == "viz"
Requires-Dist: pyvistaqt>=0.11.1; extra == "viz"
Requires-Dist: vtk>=9.3; extra == "viz"
Provides-Extra: riemann
Requires-Dist: pyriemann>=0.7; extra == "riemann"
Provides-Extra: bids
Requires-Dist: mne-bids>=0.14; extra == "bids"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Requires-Dist: mypy; extra == "lint"
Requires-Dist: pre-commit; extra == "lint"
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.14; extra == "docs"
Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
Requires-Dist: numpydoc>=1.6; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
Requires-Dist: sphinx-tabs>=3.4; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == "docs"
Requires-Dist: seaborn>=0.12; extra == "docs"
Provides-Extra: full
Requires-Dist: pyvista>=0.44; extra == "full"
Requires-Dist: pyvistaqt>=0.11.1; extra == "full"
Requires-Dist: vtk>=9.3; extra == "full"
Requires-Dist: pyriemann>=0.7; extra == "full"
Requires-Dist: mne-bids>=0.14; extra == "full"
Requires-Dist: pytest; extra == "full"
Requires-Dist: pytest-cov; extra == "full"
Requires-Dist: ruff; extra == "full"
Requires-Dist: mypy; extra == "full"
Requires-Dist: pre-commit; extra == "full"
Requires-Dist: sphinx>=7; extra == "full"
Requires-Dist: pydata-sphinx-theme>=0.14; extra == "full"
Requires-Dist: sphinx-gallery>=0.15; extra == "full"
Requires-Dist: numpydoc>=1.6; extra == "full"
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "full"
Requires-Dist: sphinx-tabs>=3.4; extra == "full"
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == "full"
Requires-Dist: seaborn>=0.12; extra == "full"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/payamsash/mne-rt/main/docs/source/_static/mne_rt_logo.svg" alt="MNE-RT Logo" width="480"/>
</p>

<p align="center">
  <strong>MNE-RT — Real-time M/EEG Signal Processing</strong><br>
  From amplifier to 3-D brain display in a single, researcher-friendly API
</p>

<p align="center">
  <a href="https://github.com/payamsash/mne-rt/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/payamsash/mne-rt?color=green"></a>
  <a href="https://pypi.org/project/mne-rt/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mne-rt?color=blue"></a>
  <a href="https://pypi.org/project/mne-rt/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/mne-rt"></a>
  <a href="https://payamsash.github.io/mne-rt/"><img alt="Docs" src="https://img.shields.io/badge/docs-online-brightgreen?logo=readthedocs&logoColor=white"></a>
</p>

---

**MNE-RT** is an open-source Python library for **real-time M/EEG signal
processing**, built on [MNE-Python](https://mne.tools) and
[MNE-LSL](https://mne.tools/mne-lsl). It covers the full closed-loop pipeline —
from amplifier to 3-D brain display — in a single API designed for neurofeedback,
BCI, and clinical or basic-science monitoring.

## Highlights

| Feature | Details |
|---|---|
| **20 NF modalities** | Band power, ERD/ERS, laterality, Hjorth, spectral centroid, CFC, connectivity, graph Laplacian — sensor and source space |
| **10 adaptive protocols** | Z-score, threshold, percentile, staircase, operant, RL, sham, multi-band, and cross-session transfer |
| **5 artifact correction methods** | ASR, adaptive LMS, GEDAI, ORICA, real-time Maxwell/SSS (MEG) |
| **9 live visualisation windows** | Scrolling raw · NF signal · epoch overlays · scalp topo · 3-D brain · butterfly · ERP comparison · TFR heatmaps |
| **Feature combiners** | Weighted sum, geometric mean, z-scored norm, or any sklearn estimator |
| **External feedback output** | OSC (Max/MSP, SuperCollider) and LSL outlet (PsychoPy, OpenViBE, BCI2000) |
| **BIDS-compatible saving** | Session JSON + TSV with full metadata, artifact rate, and SNR |
| **CLI** | `mne-rt info` · `mne-rt demo` · `mne-rt baseline` · `mne-rt run` |
| **Mock mode** | Full pipeline without hardware via built-in LSL replay |

## Installation

```bash
pip install mne-rt                 # core package
pip install "mne-rt[full]"         # + 3-D viz, dev tools, docs
```

<details>
<summary>Other installation methods</summary>

**uv (fast Rust-based installer):**
```bash
uv pip install mne-rt
uv pip install "mne-rt[full]"
```

**Development install from source:**
```bash
git clone https://github.com/payamsash/mne-rt.git
cd mne-rt
pip install -e ".[dev]"
```

</details>

Verify:
```bash
mne-rt info     # prints MNE-RT and dependency versions
mne-rt demo     # runs a 60-second mock neurofeedback session
```

## Quick start

```python
from mne_rt import RTStream
from mne_rt.protocols import ZScoreProtocol

# 1 — Create a session object
nf = RTStream(
    subject_id="sub01",
    session="01",
    subjects_dir="/data/subjects",
    montage="easycap-M1",
)

# 2 — Connect to a live LSL stream (or replay a file without hardware)
nf.connect_to_lsl(mock_lsl=True)

# 3 — Record a resting-state baseline (bad channels, ICA, noise cov)
nf.record_baseline(duration=120)

# 4 — Run a closed-loop NF session
nf.record_main(
    duration=300,
    modality=["sensor_power", "erd_ers"],
    protocol=ZScoreProtocol(direction="up", zscore_threshold=0.5),
    show_nf_signal=True,
    show_topo=True,
)

# 5 — Save results (BIDS-compatible JSON + TSV)
nf.save()
```

## CLI

```bash
# Print version and all dependency versions
mne-rt info

# Quick demo — no amplifier needed
mne-rt demo --duration 60 --modality sensor_power erd_ers

# Record a resting-state baseline
mne-rt baseline --subject sub01 --subjects-dir /data --session 01

# Run a full session with artifact correction and live displays
mne-rt run --subject sub01 --subjects-dir /data --duration 600 \
           --modality sensor_power erd_ers \
           --artifact-correction asr \
           --topo --brain
```

## Documentation

Full documentation (API reference, tutorials, visualization gallery) is available at
**[payamsash.github.io/mne-rt](https://payamsash.github.io/mne-rt/)**.

## Cite

If you use MNE-RT in your research, please cite:

```bibtex
@inproceedings{shabestari2025advances,
  title        = {Advances on Real Time {M/EEG} Neural Feature Extraction},
  author       = {Shabestari, Payam S and Ribes, Delphine and D{\'e}fayes, Lara
                  and Cai, Danpeng and Groves, Emily and Behjat, Harry H
                  and Van de Ville, Dimitri and Kleinjung, Tobias
                  and Naas, Adrian and Henchoz, Nicolas and others},
  booktitle    = {2025 IEEE 38th International Symposium on Computer-Based
                  Medical Systems (CBMS)},
  pages        = {337--338},
  year         = {2025},
  organization = {IEEE}
}
```

## Acknowledgements

Development was supported by the
[Swiss National Science Foundation](https://www.snf.ch/en) (grant 208164 —
*Advancing Neurofeedback in Tinnitus*).

## License

[MIT License](LICENSE) — © 2025 Payam S. Shabestari
