Mne Python Guide

MNE-Python Analysis Guide

Purpose

This skill encodes expert methodological knowledge for analyzing neurophysiological data (EEG, MEG, sEEG, ECoG, NIRS, eye-tracking) using MNE-Python (Gramfort et al., 2013; Gramfort et al., 2014). It covers the complete analysis pipeline with recommended parameters, code examples, and common pitfall warnings.

When to Use This Skill

Activate when the user:

• Asks about EEG/MEG/sEEG/ECoG/NIRS data analysis in Python
• Mentions MNE, MNE-Python, epochs, evoked, Raw, source estimate, ICA, ERP, ERF
• Wants to load neurophysiological data files (.fif, .edf, .bdf, .set, .vhdr, .mff, .cnt, .snirf)
• Needs preprocessing, time-frequency, source localization, decoding, or statistical testing guidance
• Wants to create MNE objects from numpy arrays or simulate data

Research Planning Protocol

1. State the research question — What is the user investigating?
2. Justify the method choice — Confirm MNE-Python fits their data type and goal.
3. Declare expected outcomes — What output format? (ERP plots, TFR maps, source maps, decoding accuracy)
4. Note assumptions and limitations — Data quality, sample size, MRI availability, montage info.
5. Present the plan and WAIT for confirmation before writing code.

Verification Notice

This skill was generated by AI from MNE-Python source code and academic literature. All parameters, thresholds, and citations require independent verification. If you find errors, please open an issue at https://github.com/NeuroAIHub/awesome_cognitive_and_neuroscience_skills/issues.

Reference Files (Progressive Disclosure)

This skill uses layered references. Read the relevant file when the user's question goes deeper than the overview below:

Pipeline Overview

Copy code
Raw → Mark bad channels → Filter → ICA → Re-reference → Resample
  → Epochs → Evoked (ERP/ERF)
  → Time-Frequency (TFR/PSD)
  → Source Localization (MNE/dSPM/LCMV)
  → Decoding (MVPA)
  → Statistics (cluster permutation)

Core Data Structures

All objects carry an info attribute (mne.Info) with channel metadata that propagates through the pipeline.

Quick Start Pipeline

pythonCopy code
import mne
import numpy as np

# 1. Load
raw = mne.io.read_raw_fif('data_raw.fif', preload=True)
# or: raw = mne.io.read_raw_edf('data.edf', preload=True)

# 2. Preprocess
raw.filter(l_freq=0.1, h_freq=40.)           # bandpass
raw.notch_filter(freqs=[50, 100])              # line noise
ica = mne.preprocessing.ICA(n_components=20, random_state=97, max_iter=800)
ica.fit(raw.copy().filter(l_freq=1., h_freq=None))  # fit on 1 Hz highpass copy
eog_idx, _ = ica.find_bads_eog(raw)
ica.exclude = eog_idx
ica.apply(raw)
raw.set_eeg_reference('average')

# 3. Epoch
events, event_id = mne.events_from_annotations(raw)
epochs = mne.Epochs(raw, events, event_id, tmin=-0.2, tmax=0.5,
                    baseline=(None, 0), preload=True,
                    reject=dict(eeg=150e-6))

# 4. ERP
evoked = epochs['target'].average()
evoked.plot_joint()

# 5. Time-frequency
freqs = np.arange(4, 30, 2)
power = epochs.compute_tfr(method="morlet", freqs=freqs, n_cycles=freqs / 2.)
power.plot()

# 6. Source localization (requires anatomy)
noise_cov = mne.compute_covariance(epochs, tmax=0., method='auto')
fwd = mne.read_forward_solution('sample-fwd.fif')
inv = mne.minimum_norm.make_inverse_operator(epochs.info, fwd, noise_cov)
stc = mne.minimum_norm.apply_inverse(evoked, inv, lambda2=1./9., method='dSPM')

# 7. Decoding
from mne.decoding import SlidingEstimator, cross_val_multiscore
from sklearn.linear_model import LogisticRegression
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler
X = epochs.get_data(copy=True)
y = epochs.events[:, -1]
clf = make_pipeline(StandardScaler(), LogisticRegression(solver='liblinear'))
slider = SlidingEstimator(clf, scoring='roc_auc')
scores = cross_val_multiscore(slider, X, y, cv=5)

# 8. Statistics
from mne.stats import spatio_temporal_cluster_test
adjacency, _ = mne.channels.find_ch_adjacency(epochs.info, 'eeg')
T_obs, clusters, p_values, H0 = spatio_temporal_cluster_test(
    [X_cond1, X_cond2], adjacency=adjacency, n_permutations=1000)

Common Pitfalls

1. ICA on unfiltered data — Highpass ≥1 Hz before ICA fitting; slow drifts degrade decomposition (Jas et al., 2018)
2. Baseline correction before ICA — Apply baseline after ICA, not before
3. Filtering after epoching — Filter Raw, not Epochs, to avoid edge artifacts (Luck, 2014)
4. Wrong rejection thresholds — Start with EEG 100–150 µV, adjust via epochs.plot_drop_log()
5. Forgetting preload=True — Many operations require data in memory
6. Re-referencing timing — Set reference after ICA but before epoching
7. Events after resampling — Recompute events after downsampling, or resample Epochs directly
8. Legacy API — Use epochs.compute_tfr() / raw.compute_psd() instead of deprecated tfr_morlet() / psd_welch()
9. Decoding data leakage — Always cross-validate; never fit scaler on test data
10. Cluster test interpretation — Clusters show where effects exist, not their spatial/temporal extent (Maris & Oostenveld, 2007)

References

• Blankertz, B., et al. (2008). Optimizing spatial filters for robust EEG single-trial analysis. IEEE Signal Processing Magazine, 25(1), 41–56.
• Dale, A. M., et al. (2000). Dynamic statistical parametric mapping. Neuron, 26(1), 55–67.
• Gramfort, A., et al. (2013). MEG and EEG data analysis with MNE-Python. Frontiers in Neuroscience, 7, 267.
• Gramfort, A., et al. (2014). MNE software for processing MEG and EEG data. NeuroImage, 86, 446–460.
• Jas, M., et al. (2018). Autoreject: Automated artifact rejection for MEG and EEG data. NeuroImage, 159, 417–429.
• King, J.-R., & Dehaene, S. (2014). Characterizing the dynamics of mental representations. Trends in Cognitive Sciences, 18(4), 203–210.
• Luck, S. J. (2014). An Introduction to the Event-Related Potential Technique. MIT Press.
• Maris, E., & Oostenveld, R. (2007). Nonparametric statistical testing of EEG- and MEG-data. Journal of Neuroscience Methods, 164(1), 177–190.
• Pascual-Marqui, R. D. (2002). Standardized low-resolution brain electromagnetic tomography. Methods and Findings in Experimental and Clinical Pharmacology, 24(Suppl D), 5–12.
• Tallon-Baudry, C., et al. (1997). Oscillatory gamma-band activity induced by a visual search task. Journal of Neuroscience, 17(2), 722–734.