mne-python-guide
Skill39 starsChanged 9 months agoMITView on GitHub
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.
In this repository49 other files it gives its agents.
- act-r-model-builderSkill
- alternative-uses-task-designerSkill
- bayesian-cognitive-model-builderSkill
- brain-connectivity-modelerSkill
- calcium-imaging-analysis-guideSkill
- cognitive-paradigm-designSkill
- cogsci-power-analysisSkill
- cogsci-statisticsSkill
- cogsci-visualizationSkill
- contribute-skillSkill
- contribute-skills-via-prSkill
- creativity-self-efficacy-mediationSkill
- deeplabcutSkill
- divergent-thinking-scoringSkill
- drift-diffusion-modelSkill
- eeg-paradigm-designerSkill
- eeg-preprocessing-pipeline-guideSkill
- erp-analysisSkill
- evidence-accumulation-selectorSkill
- fmri-glm-analysis-guideSkill
- fmri-preprocessing-pipeline-guideSkill
- fmriprepSkill
- fmri-task-design-guideSkill
- infant-looking-time-designerSkill
- lesion-symptom-mapping-guideSkill
- markdown-report-writingSkill
- netneurotools-guideSkill
- neural-decoding-analysisSkill
- neural-population-analysis-guideSkill
- neuroimaging-power-guideSkill
- neuroimaging-sample-size-calculatorSkill
- neuropsych-battery-selectorSkill
- optogenetics-protocol-designerSkill
- paper-to-skillSkill
- parameter-recovery-checkerSkill
- pycortex-guideSkill
- reading-time-analysisSkill
- repo-to-skillSkill
- research-literacySkill
- self-paced-reading-designerSkill
- sentence-stimulus-normingSkill
- share-caseSkill
- share-usageSkill
- signal-detection-analysisSkill
- spikeinterface-skillSkill
- spiking-network-model-builderSkill
- tom-task-selectorSkill
- verify-skillSkill
- visual-search-array-generatorSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 46
Present the plan and WAIT for confirmation: before writing code.
- Very specific: line 89
All objects carry an info attribute (mne.Info) with channel metadata that propagates through the pipeline.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- State the research question — What is the user investigating?
- Justify the method choice — Confirm MNE-Python fits their data type and goal.
- Declare expected outcomes — What output format? (ERP plots, TFR maps, source maps, decoding accuracy)
- Note assumptions and limitations — Data quality, sample size, MRI availability, montage info.
- 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
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
- ICA on unfiltered data — Highpass ≥1 Hz before ICA fitting; slow drifts degrade decomposition (Jas et al., 2018)
- Baseline correction before ICA — Apply baseline after ICA, not before
- Filtering after epoching — Filter Raw, not Epochs, to avoid edge artifacts (Luck, 2014)
- Wrong rejection thresholds — Start with EEG 100–150 µV, adjust via
epochs.plot_drop_log() - Forgetting
preload=True— Many operations require data in memory - Re-referencing timing — Set reference after ICA but before epoching
- Events after resampling — Recompute events after downsampling, or resample Epochs directly
- Legacy API — Use
epochs.compute_tfr()/raw.compute_psd()instead of deprecatedtfr_morlet()/psd_welch() - Decoding data leakage — Always cross-validate; never fit scaler on test data
- 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

