CMNE

Contextual Minimum-Norm Estimates for MEG and EEG

An LSTM learns how brain activity evolves over time and uses that context to sharpen standard source estimates such as dSPM.

_{Simulated burst travelling across five sources (red: true peak source). CMNE suppresses background activity that dSPM leaves in. Generated by examples/quickstart_simulation.py.}

Contents

• How it works
• Installation
• Quick start
• Reproducing the paper
• Running on modest hardware
• API overview
• Changes from the original code
• Citation

How it works

Methods such as MNE, dSPM and sLORETA estimate every time sample on its own. Brain activity, however, unfolds over time: what happens now depends on what happened just before. CMNE uses this context in three steps.

1. Estimate. Compute a standard source estimate $\hat q_t$ (dSPM), rectify it and z-score each source.
2. Predict. Give the last $k$ CMNE estimates $b_{t-k}, \dots, b_{t-1}$ to an LSTM network, which predicts the next estimate.
3. Correct. Use the prediction, scaled to a maximum of one, as a per-source weight on the current estimate:

$$ b_t = w_t \odot \hat q_t, \qquad w_t = \frac{\left| \mathrm{LSTM}(b_{t-k}, \dots, b_{t-1}) \right|}{\max \left| \mathrm{LSTM}(b_{t-k}, \dots, b_{t-1}) \right|} $$

For the first $k$ samples there is no history yet, so $b_t = \hat q_t$. Each new $b_t$ is fed back into the LSTM, so the estimate is refined recursively.

In the paper, CMNE gave higher source-space SNR, lower spatial dispersion and smaller localisation errors than dSPM, both on simulated epileptiform spikes and on recorded auditory steady-state responses (ASSR).

Features

Installation

pip install cmne            # PyTorch + MNE-Python
pip install "cmne[onnx]"    # adds ONNX export and ONNX Runtime
pip install "cmne[viz]"     # adds matplotlib for the examples

For GPU training, install the matching PyTorch build first; CMNE picks it up automatically.

git clone https://github.com/chdinh/cmne && cd cmne
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Quick start

Try it in seconds

cmne demo

This trains a small model on simulated EEG on the CPU and compares it with dSPM at the peak of the activity:

dSPM  peak error  46.2 mm   spatial dispersion  58.4 mm
CMNE  peak error   0.0 mm   spatial dispersion  40.0 mm

Python

import cmne
from mne.minimum_norm import apply_inverse

# epochs: mne.Epochs, inv: mne.minimum_norm.InverseOperator
kernel = cmne.inverse_kernel(epochs.info, inv, lambda2=1 / 9, method="dSPM")

# Train on single-trial dSPM estimates (paper settings: k = 80, d = 1280)
model = cmne.fit(
    epochs[train], kernel, look_back=80, num_units=1280, n_steps=250, validation=epochs[test]
)
model.save("cmne.pt")

# Apply to an averaged response
stc = apply_inverse(epochs[test].average(), inv, 1 / 9, "dSPM", pick_ori="normal")
result = cmne.apply_cmne(stc, model)
result.cmne.plot(subject="sample", subjects_dir=subjects_dir)

apply_cmne returns three estimates:

They are SourceEstimate objects if the input was one, NumPy arrays otherwise. To process many signals at once, pass an array of shape (n_signals, n_sources, n_times).

ONNX Runtime

cmne.export_onnx(model, "cmne.onnx")
predictor = cmne.OnnxPredictor("cmne.onnx")  # PyTorch not required
result = cmne.apply_cmne(stc, predictor)

Command line

cmne train  --raw sub01_raw.fif --inv sub01-inv.fif --events sub01-eve.fif -o cmne.pt
cmne export cmne.pt -o cmne.onnx
cmne apply  --raw sub01_raw.fif --inv sub01-inv.fif --events sub01-eve.fif \
            --model cmne.onnx --n-average 20 -o results/

cmne <command> --help lists all options, including epoch window, rejection thresholds, MEG-only, look-back and number of units.

Reproducing the paper

The ASSR data set used in the paper (MEG + EEG, ~4.3 GB) is available on OSF. The script downloads it on first use:

python examples/assr_paper.py --data ~/cmne_data              # paper settings
python examples/assr_paper.py --data ~/cmne_data --units 256   # faster, for laptops

Running on modest hardware

Most parameters sit in the LSTM input layer, which grows with the number of units $d$ times the number of sources. For 5,124 sources:

If memory is still tight, lower epochs_per_batch and windows_per_epoch (default 30 × 20 = 600 windows per step).

Inference speed at paper scale on an Apple M-series CPU (python benchmarks/bench_inference.py):

API overview

Changes from the original code

Version 0.2 is a rewrite of the 2017–2022 research code, which is kept in archive/. Besides moving from TensorFlow/Keras to PyTorch, it fixes:

• Normalisation mismatch. The network was trained on signed z-scored dSPM but applied to rectified, max-normalised dSPM. Both now use Eq. 9.
• Weighting. The estimate was multiplied by the raw, possibly negative prediction instead of the normalised weight of Eq. 11. The old behaviour remains available with normalize_weights=False.
• Windowing. One valid training window per epoch was dropped.
• Crashes. train() used undefined variables and returned nothing; Data indexed a method and compared arrays with == None; Settings failed if the results folder did not exist.
• Hard-coded sizes. The evaluation assumed 5,124 sources and $k$ = 80; both now come from the model.
• Robustness. Division by zero for constant sources; the data download relied on shell mv/rm.

Citation

If CMNE is useful for your work, please cite:

Dinh C, Samuelsson JG, Hunold A, Hämäläinen MS, Khan S. Contextual MEG and EEG Source Estimates Using Spatiotemporal LSTM Networks. Frontiers in Neuroscience 15:552666 (2021). doi:10.3389/fnins.2021.552666

@article{dinh2021cmne,
  title   = {Contextual {MEG} and {EEG} Source Estimates Using Spatiotemporal {LSTM} Networks},
  author  = {Dinh, Christoph and Samuelsson, John G. and Hunold, Alexander and
             H{\"a}m{\"a}l{\"a}inen, Matti S. and Khan, Sheraz},
  journal = {Frontiers in Neuroscience},
  volume  = {15},
  pages   = {552666},
  year    = {2021},
  doi     = {10.3389/fnins.2021.552666}
}

An earlier version is available as a preprint: arXiv:1909.02636.

License

MIT © 2017–2026 the CMNE authors.