# Mne Python Guide

> Domain-validated pipeline guidance for EEG/MEG data analysis using MNE-Python: data loading, preprocessing (filtering, ICA, re-referencing), epoching, ERP/ERF computation, time-frequency decomposition, source localization, decoding/MVPA, statistical testing, simulation, and visualization. Use this skill whenever the user works with EEG/MEG/sEEG/ECoG/NIRS/eye-tracking data in Python, mentions MNE, or needs neurophysiological analysis guidance.

- Skill: `neuroaihub/mne-python-guide` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add neuroaihub/mne-python-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neuroaihub/mne-python-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: neuroaihub (https://skillmd.com/u/neuroaihub)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neuroaihub/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:

| Topic | Reference File | When to Read |
|-------|---------------|--------------|
| Data I/O (30+ formats) | `references/io_formats.md` | User asks about loading specific file formats, creating objects from arrays, or exporting |
| Preprocessing | `references/preprocessing.md` | User needs ICA details, Maxwell filtering, artifact annotation, bad channel detection, CSD, fNIRS/iEEG-specific preprocessing |
| Time-Frequency | `references/time_frequency.md` | User asks about TFR methods, PSD, CSD, baseline modes, array-level functions |
| Source Localization | `references/source_localization.md` | User needs forward modeling, inverse methods, beamformers, dipole fitting details |
| Decoding & MVPA | `references/decoding.md` | User asks about classification, temporal generalization, CSP, SPoC, receptive fields |
| Statistics | `references/statistics.md` | User needs cluster permutation, TFCE, ANOVA, adjacency matrices, correction methods |
| Visualization | `references/visualization.md` | User asks about plotting functions, publication figures, 3D brain rendering |
| Simulation | `references/simulation.md` | User wants to create synthetic data, simulate sources, add artifacts |

## Pipeline Overview

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

| Object | Description | Create from |
|--------|-------------|-------------|
| `Raw` | Continuous data | `mne.io.read_raw_*()` or `mne.io.RawArray(data, info)` |
| `Epochs` | Event-segmented data | `mne.Epochs(raw, events, ...)` or `mne.EpochsArray(data, info)` |
| `Evoked` | Averaged epochs | `epochs.average()` or `mne.EvokedArray(data, info)` |
| `SourceEstimate` | Brain-mapped activity | `apply_inverse(evoked, inv, ...)` |
| `Spectrum` | Power spectrum | `raw.compute_psd()` or `epochs.compute_psd()` |
| `AverageTFR` | Time-frequency map | `epochs.compute_tfr(method, freqs, ...)` |

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

## Quick Start Pipeline

```python
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.