Metadata-Version: 2.4
Name: mne-rt
Version: 1.2.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: BSD-3-Clause
Project-URL: Homepage, https://github.com/mne-rt-org/mne-rt
Project-URL: Documentation, https://mne-rt-org.github.io/mne-rt/
Project-URL: Repository, https://github.com/mne-rt-org/mne-rt
Project-URL: Bug Tracker, https://github.com/mne-rt-org/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.9
Requires-Dist: mne-lsl>=1.7
Requires-Dist: mne-connectivity>=0.8
Requires-Dist: mne-features>=0.3
Requires-Dist: mne-icalabel>=0.5
Requires-Dist: scikit-learn>=1.4.2
Requires-Dist: numpy<3,>=2.0
Requires-Dist: scipy>=1.13
Requires-Dist: matplotlib>=3.9
Requires-Dist: nibabel>=5.2
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: imageio[ffmpeg]>=2.28
Provides-Extra: pyqt6
Requires-Dist: PyQt6>=6.7; extra == "pyqt6"
Provides-Extra: pyside6
Requires-Dist: PySide6>=6.7; extra == "pyside6"
Provides-Extra: osc
Requires-Dist: python-osc>=1.8; extra == "osc"
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>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; 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>=8.0; extra == "full"
Requires-Dist: pytest-cov>=5.0; 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/mne-rt-org/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/mne-rt-org/mne-rt/blob/main/LICENSE"><img alt="License: BSD-3-Clause" src="https://img.shields.io/badge/license-BSD--3--Clause-green"></a>
  <a href="https://github.com/mne-rt-org/mne-rt/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mne-rt-org/mne-rt/actions/workflows/ci.yml/badge.svg"></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://mne-rt-org.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.

## Ecosystem

Several MNE-affiliated packages address real-time M/EEG at different levels of
abstraction. Here is how they relate:

**[mne-realtime](https://github.com/mne-tools/mne-realtime)** was the original
real-time extension for [MNE-Python](https://mne.tools). It offered TCP/IP client
classes for a handful of acquisition systems (FieldTrip buffer, RtClient,
StimServer) and a basic `RtEpochs` object for online epoching and classification.
The package is **no longer maintained** and should not be used for new projects.

**[mne-lsl](https://mne.tools/mne-lsl)** is an actively maintained, low-to-mid-level
streaming library. It provides modern Python bindings for the
[Lab Streaming Layer (LSL)](https://github.com/sccn/labstreaminglayer) C++ library 
(replacement for the older [pylsl](https://github.com/labstreaminglayer/pylsl))
— together with high-level objects: `StreamInlet` and `StreamOutlet` for reading
and writing LSL streams, `StreamPlayer` for replaying recorded files without
hardware, `StreamRecorder` for saving streams to disk, and `EpochStream` for
real-time epoching with online filtering. [MNE-RT](https://mne-rt-org.github.io/mne-rt/) 
uses [MNE-LSL](https://mne.tools/mne-lsl) as its data-acquisition backbone.

**[MNE-RT](https://mne-rt-org.github.io/mne-rt/)** (this package) is an actively
maintained, high-level neurofeedback and BCI application framework built on top of
[MNE-Python](https://mne.tools) and [MNE-LSL](https://mne.tools/mne-lsl). It adds
the full closed-loop pipeline that neither of the above provides: **neural
feature extraction modalities** spanning sensor and source space; **adaptive feedback
protocols**; **online artifact correction methods**; and **live visualisation windows**.
It also handles feature combining, external feedback output via OSC and LSL outlets,
BIDS-compatible session saving, and a full CLI.

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

**conda / mamba ([conda-forge](https://anaconda.org/conda-forge/mne-rt)):**
```bash
mamba install -c conda-forge mne-rt
# or, with plain conda:
conda install -c conda-forge mne-rt
```

**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/mne-rt-org/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
**[mne-rt-org.github.io/mne-rt](https://mne-rt-org.github.io/mne-rt/)**.

## Getting help

- **Documentation** — [mne-rt-org.github.io/mne-rt](https://mne-rt-org.github.io/mne-rt/)
- **Questions** — [GitHub Discussions](https://github.com/mne-rt-org/mne-rt/discussions)
- **Bugs** — [GitHub Issues](https://github.com/mne-rt-org/mne-rt/issues); see
  [SUPPORT.md](SUPPORT.md) for what to include
- **Contributing** — see [CONTRIBUTING.md](CONTRIBUTING.md) and our
  [Code of Conduct](CODE_OF_CONDUCT.md)

## 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 Sonderegger, Andreas and Neff, Patrick},
  booktitle    = {2025 IEEE 38th International Symposium on Computer-Based
                  Medical Systems (CBMS)},
  publisher    = {IEEE},
  year         = {2025},
  pages        = {337--338},
  doi          = {10.1109/CBMS65348.2025.00074}
}
```

## Acknowledgements

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

## License

[BSD 3-Clause License](LICENSE) — © 2024–2026 Payam S. Shabestari
