Advanced Neurofeedback Toolbox
Real-time M/EEG neurofeedback for research and clinical use

---

ANT is an open-source Python package for real-time closed-loop M/EEG neurofeedback. Built on MNE-Python and the Lab Streaming Layer (LSL), it covers the full pipeline — from amplifier to 3D brain display — in a single, researcher-friendly API.

Highlights

Feature	Details
20+ NF modalities	Band power, ERD/ERS, laterality, Hjorth parameters, spectral centroid, slow cortical potentials, CFC, functional connectivity, graph Laplacian — in sensor and source space
Adaptive protocols	Z-score, threshold, percentile, staircase, operant, reinforcement learning, sham, and transfer — all evaluated inside the acquisition loop on every analysis window
Real-time artifact correction	ASR, adaptive LMS, GEDAI (GED-based spatial filters), ORICA (online ICA), Riemannian covariance detection
Real-time Maxwell filtering	Pre-computed SSS/tSSS projector for zero-latency MEG denoising; numerically equivalent to offline MNE
Three live displays	Raw stream viewer · NF signal monitor · 3D cortical activation map — all updating at ~30 fps via a shared Qt event loop
External output	OSC (Max/MSP, SuperCollider, Pure Data) and LSL outlet (PsychoPy, OpenViBE, Psychtoolbox) for reward delivery to any application
BIDS-compatible saving	Session data saved as JSON + optional TSV with full metadata, artifact rate, and SNR
CLI	ANT info · ANT demo · ANT baseline · ANT run — no Python required
Mock mode	Full pipeline without hardware via built-in LSL replay from any MNE-readable file

Installation

pip install ant-nf                 # core package
pip install "ant-nf[full]"         # all extras: viz, dev, docs

Other installation methods

uv (fast Rust-based installer):

uv pip install ant-nf

conda / mamba:

conda env create -f environment.yml
conda activate ant

Development install from source:

git clone https://github.com/payamsash/ANT.git
cd ANT
pip install -e ".[dev]"

Verify the installation:

ANT info     # print ANT version and all key dependency versions
ANT demo     # run a 60-second mock neurofeedback session

Quick start

from ant import NFRealtime
from ant.protocols import ZScoreProtocol

# 1 — Create a session object
nf = NFRealtime(
    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
nf.record_baseline(baseline_duration=120)

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

# 5 — Save results (JSON + companion TSV)
nf.save(bids_tsv=True)

CLI

# Print ANT version and all dependency versions
ANT info

# Quick demo — no amplifier or files needed (default: 120 s)
ANT demo --duration 60 --modality sensor_power erd_ers laterality

# Record a resting-state baseline from a live LSL stream
ANT baseline --subject sub01 --subjects-dir /data --session 01 --duration 120

# Record a baseline from a file (mock mode)
ANT baseline --subject sub01 --subjects-dir /data --mock --fname recording.fif

# Run a full session with real-time artifact correction and displays
ANT run --subject sub01 --subjects-dir /data --duration 600 \
        --modality sensor_power erd_ers laterality \
        --artifact-correction asr \
        --topo --brain

# Stream reward values to Max/MSP or SuperCollider via OSC
ANT run --subject sub01 --subjects-dir /data --duration 600 \
        --modality sensor_power laterality \
        --osc-host 127.0.0.1 --osc-port 9000

# Broadcast NF values as an LSL outlet (PsychoPy, OpenViBE, Psychtoolbox …)
ANT run --subject sub01 --subjects-dir /data --duration 600 \
        --modality sensor_power --lsl-output

Cite

If you use ANT in your research, please cite:

@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 (grant number 208164 — Advancing Neurofeedback in Tinnitus).

License

MIT License — © 2025 Payam S. Shabestari