@brainpilot/skills 0.0.6

package/skills/05_EEG_ERP/mne-python-guide/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: "mne-python-guide"
+description: "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."
+domain: "neuroimaging-methods"
+version: "2.0.0"
+authors:
+  - "Claude (AI-assisted)"
+papers:
+  - "Gramfort et al., 2013"
+  - "Gramfort et al., 2014"
+  - "Luck, 2014"
+  - "Jas et al., 2018"
+  - "Dale et al., 2000"
+  - "Pascual-Marqui, 2002"
+  - "Tallon-Baudry et al., 1997"
+  - "Maris & Oostenveld, 2007"
+  - "Blankertz et al., 2008"
+  - "King & Dehaene, 2014"
+dependencies:
+  required:
+    - research-literacy
+review_status: "ai-generated"
+---
+
+# 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.

package/skills/05_EEG_ERP/mne-python-guide/references/decoding.md

@@ -0,0 +1,178 @@
+# Decoding & MVPA Reference
+
+## Table of Contents
+1. [MNE Transformers](#transformers)
+2. [Temporal Decoding](#temporal-decoding)
+3. [Temporal Generalization](#temporal-generalization)
+4. [CSP (Common Spatial Patterns)](#csp)
+5. [SPoC, SSD, Xdawn](#spoc-ssd-xdawn)
+6. [Receptive Field Estimation](#receptive-field)
+7. [Source-Space Decoding](#source-decoding)
+8. [Utility Functions](#utilities)
+
+## MNE Transformers (sklearn-compatible)
+
+| Transformer | Purpose |
+|-------------|---------|
+| `Scaler(info, scalings='mean')` | Channel-type-aware standardization |
+| `Vectorizer()` | Reshape (n_epochs, n_ch, n_times) → (n_epochs, n_features) |
+| `FilterEstimator(info, l_freq, h_freq)` | Temporal filtering in pipeline |
+| `TemporalFilter(l_freq, h_freq)` | Temporal filtering (no info needed) |
+| `PSDEstimator(sfreq, fmin, fmax)` | PSD features |
+| `TimeFrequency(freqs, sfreq)` | TFR features |
+| `UnsupervisedSpatialFilter(PCA(10))` | Spatial PCA/ICA |
+| `LinearModel(LogisticRegression())` | Wrapper for pattern extraction |
+
+## Temporal Decoding
+
+Fit a classifier at each time point independently (King & Dehaene, 2014):
+
+```python
+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)  # (n_epochs, n_channels, n_times)
+y = epochs.events[:, -1]
+
+clf = make_pipeline(StandardScaler(), LogisticRegression(solver='liblinear'))
+slider = SlidingEstimator(clf, scoring='roc_auc', n_jobs=-1)
+scores = cross_val_multiscore(slider, X, y, cv=5)
+# scores shape: (n_folds, n_times)
+
+# Plot
+import matplotlib.pyplot as plt
+fig, ax = plt.subplots()
+ax.plot(epochs.times, scores.mean(axis=0))
+ax.axhline(0.5, color='k', linestyle='--')
+ax.set(xlabel='Time (s)', ylabel='AUC', title='Temporal Decoding')
+```
+
+## Temporal Generalization
+
+Train at each time, test at all times — reveals dynamics of neural representations:
+
+```python
+from mne.decoding import GeneralizingEstimator
+
+gen = GeneralizingEstimator(clf, scoring='roc_auc', n_jobs=-1)
+scores = cross_val_multiscore(gen, X, y, cv=5)
+# scores shape: (n_folds, n_train_times, n_test_times)
+
+# Plot generalization matrix
+fig, ax = plt.subplots()
+im = ax.imshow(scores.mean(axis=0), origin='lower', cmap='RdBu_r',
+               extent=epochs.times[[0, -1, 0, -1]], vmin=0.3, vmax=0.7)
+ax.set(xlabel='Test time (s)', ylabel='Train time (s)')
+ax.axhline(0, color='k'); ax.axvline(0, color='k')
+plt.colorbar(im, ax=ax, label='AUC')
+```
+
+## CSP
+
+Common Spatial Patterns for two-class discrimination (Blankertz et al., 2008):
+
+```python
+from mne.decoding import CSP
+
+csp = CSP(n_components=4, reg=None, log=True, norm_trace=False)
+clf = make_pipeline(csp, LogisticRegression(solver='liblinear'))
+scores = cross_val_multiscore(clf, X, y, cv=5)
+
+# Visualize spatial patterns and filters
+csp.fit(X, y)
+csp.plot_patterns(epochs.info)   # neurophysiologically interpretable
+csp.plot_filters(epochs.info)    # spatial filters applied to data
+```
+
+## SPoC, SSD, Xdawn
+
+### SPoC (Source Power Comodulation)
+For continuous target variables (not classification):
+```python
+from mne.decoding import SPoC
+from sklearn.linear_model import Ridge
+
+spoc = SPoC(n_components=2, reg='oas', log=True)
+clf = make_pipeline(spoc, Ridge())
+# Use with continuous y (e.g., reaction time, behavioral score)
+```
+
+### SSD (Spatio-Spectral Decomposition)
+Maximize signal in target band vs flanking bands:
+```python
+from mne.decoding import SSD
+
+ssd = SSD(info, filt_params_signal=dict(l_freq=8, h_freq=12),
+          filt_params_noise=dict(l_freq=6, h_freq=14))
+ssd.fit(X)
+X_ssd = ssd.transform(X)
+ssd.plot_patterns(info)
+```
+
+### Xdawn
+Enhance ERP signal for P300/BCI applications:
+```python
+from mne.decoding import XdawnTransformer
+
+xdawn = XdawnTransformer(n_components=2)
+clf = make_pipeline(xdawn, Vectorizer(), LogisticRegression())
+scores = cross_val_multiscore(clf, X, y, cv=5)
+```
+
+## Receptive Field Estimation
+
+Spectro-temporal receptive field (STRF) analysis:
+
+```python
+from mne.decoding import ReceptiveField, TimeDelayingRidge
+
+rf = ReceptiveField(
+    tmin=-0.1, tmax=0.4, sfreq=100,
+    estimator=TimeDelayingRidge(
+        tmin=-0.1, tmax=0.4, sfreq=100,
+        reg_type='laplacian', alpha=0.1
+    )
+)
+rf.fit(X_stimulus, y_response)
+rf.coef_  # receptive field weights
+rf.plot()
+```
+
+## Source-Space Decoding
+
+```python
+# Apply inverse to get source data, then decode
+stcs = apply_inverse_epochs(epochs, inv, lambda2, method='dSPM')
+X_source = np.array([stc.data for stc in stcs])  # (n_epochs, n_vertices, n_times)
+
+# Feature selection (reduce dimensionality)
+from sklearn.feature_selection import SelectKBest, f_classif
+clf = make_pipeline(
+    SelectKBest(f_classif, k=500),
+    StandardScaler(),
+    LogisticRegression()
+)
+slider = SlidingEstimator(clf, scoring='roc_auc')
+scores = cross_val_multiscore(slider, X_source, y, cv=5)
+```
+
+## Utility Functions
+
+```python
+from mne.decoding import cross_val_multiscore, get_coef, compute_ems
+
+# Cross-validation with multiple scores
+scores = cross_val_multiscore(estimator, X, y, cv=5, scoring='roc_auc')
+
+# Extract spatial patterns from LinearModel
+from mne.decoding import LinearModel
+model = LinearModel(LogisticRegression())
+model.fit(X_2d, y)
+patterns = get_coef(model, attr='patterns_')  # neurophysiological patterns
+filters = get_coef(model, attr='filters_')    # spatial filters
+
+# Effect-matched spatial filtering
+evoked_ems = compute_ems(epochs, conditions=['left', 'right'])
+```

package/skills/05_EEG_ERP/mne-python-guide/references/io_formats.md

@@ -0,0 +1,160 @@
+# I/O Formats Reference
+
+## Table of Contents
+1. [All Supported Readers](#all-supported-readers)
+2. [Auto-Detection](#auto-detection)
+3. [Creating Objects from Arrays](#creating-objects-from-arrays)
+4. [Exporting Data](#exporting-data)
+5. [Creating Info Objects](#creating-info-objects)
+
+## All Supported Readers
+
+| Function | Format | Extensions |
+|----------|--------|------------|
+| `mne.io.read_raw()` | Auto-detect | any |
+| `mne.io.read_raw_fif()` | Neuromag FIF | .fif |
+| `mne.io.read_raw_edf()` | EDF/EDF+ | .edf |
+| `mne.io.read_raw_bdf()` | BioSemi BDF | .bdf |
+| `mne.io.read_raw_gdf()` | GDF | .gdf |
+| `mne.io.read_raw_eeglab()` | EEGLAB | .set |
+| `mne.io.read_raw_brainvision()` | BrainVision | .vhdr |
+| `mne.io.read_raw_egi()` | EGI NetStation | .mff, .raw |
+| `mne.io.read_raw_cnt()` | Neuroscan CNT | .cnt |
+| `mne.io.read_raw_ctf()` | CTF MEG | .ds |
+| `mne.io.read_raw_kit()` | KIT/Ricoh | .sqd, .con |
+| `mne.io.read_raw_bti()` | BTi/4D | config |
+| `mne.io.read_raw_fieldtrip()` | FieldTrip | .mat |
+| `mne.io.read_raw_nirx()` | NIRx fNIRS | .hdr |
+| `mne.io.read_raw_snirf()` | SNIRF fNIRS | .snirf |
+| `mne.io.read_raw_boxy()` | BOXY fNIRS | .txt |
+| `mne.io.read_raw_hitachi()` | Hitachi fNIRS | .csv |
+| `mne.io.read_raw_eyelink()` | EyeLink | .asc |
+| `mne.io.read_raw_nicolet()` | Nicolet | .data |
+| `mne.io.read_raw_nihon()` | Nihon Kohden | .eeg |
+| `mne.io.read_raw_persyst()` | Persyst | .lay |
+| `mne.io.read_raw_eximia()` | Eximia | .nxe |
+| `mne.io.read_raw_ant()` | ANT Neuro | .cnt |
+| `mne.io.read_raw_curry()` | Neuroscan Curry | .cdt |
+| `mne.io.read_raw_neuralynx()` | Neuralynx | .ncs |
+| `mne.io.read_raw_nsx()` | Blackrock NSx | .ns* |
+| `mne.io.read_raw_nedf()` | NEDF | .nedf |
+| `mne.io.read_raw_fil()` | FIL | .bin |
+| `mne.io.read_raw_artemis123()` | Artemis 123 | .bin |
+
+All readers accept `preload=True/False`. Use `preload=True` for interactive analysis; `preload=False` for large files (memory-mapped).
+
+## Auto-Detection
+
+```python
+# MNE can auto-detect format from file extension
+raw = mne.io.read_raw('my_data.edf', preload=True)
+```
+
+## Creating Objects from Arrays
+
+When you have numpy arrays and want to create MNE objects:
+
+```python
+import mne
+import numpy as np
+
+# Create Info
+info = mne.create_info(
+    ch_names=['Fz', 'Cz', 'Pz', 'Oz'],
+    sfreq=256.,
+    ch_types='eeg'
+)
+info.set_montage('standard_1020')
+
+# RawArray — continuous data
+data = np.random.randn(4, 1000)  # (n_channels, n_times)
+raw = mne.io.RawArray(data, info)
+
+# EpochsArray — segmented data
+epochs_data = np.random.randn(50, 4, 128)  # (n_epochs, n_channels, n_times)
+events = np.column_stack([
+    np.arange(0, 50 * 128, 128),
+    np.zeros(50, dtype=int),
+    np.ones(50, dtype=int)
+])
+epochs = mne.EpochsArray(epochs_data, info, events, tmin=-0.2,
+                          event_id={'stimulus': 1})
+
+# EvokedArray — averaged data
+evoked_data = np.random.randn(4, 128)  # (n_channels, n_times)
+evoked = mne.EvokedArray(evoked_data, info, tmin=-0.2)
+
+# SpectrumArray — power spectrum
+psd_data = np.random.rand(4, 65)  # (n_channels, n_freqs)
+freqs = np.arange(0, 65)
+spectrum = mne.time_frequency.SpectrumArray(psd_data, info, freqs)
+```
+
+## Exporting Data
+
+```python
+raw.export('output.edf')           # to EDF
+raw.export('output.edf', fmt='edf')
+epochs.export('output.set')         # to EEGLAB
+raw.export('output.bdf', fmt='bdf') # to BDF
+```
+
+## Creating Info Objects
+
+```python
+# Basic
+info = mne.create_info(ch_names=['C3', 'C4'], sfreq=256., ch_types='eeg')
+
+# Mixed channel types
+info = mne.create_info(
+    ch_names=['EEG1', 'EEG2', 'EOG1', 'ECG1'],
+    sfreq=512.,
+    ch_types=['eeg', 'eeg', 'eog', 'ecg']
+)
+
+# Set montage (electrode positions)
+info.set_montage('standard_1020')
+# Available montages: 'standard_1020', 'standard_1005', 'biosemi64', etc.
+# List all: mne.channels.get_builtin_montages()
+
+# JSON serialization (v1.11+)
+json_dict = info.to_json_dict()
+info_restored = mne.Info.from_json_dict(json_dict)
+```
+
+## Reading Other Data Types
+
+```python
+# Events
+events = mne.read_events('events.eve')
+events, event_id = mne.events_from_annotations(raw)
+
+# Epochs from file
+epochs = mne.read_epochs('saved-epo.fif')
+
+# Evoked from file
+evoked_list = mne.read_evokeds('evoked-ave.fif')
+evoked = mne.read_evokeds('evoked-ave.fif', condition='auditory/left')
+
+# Forward solution
+fwd = mne.read_forward_solution('sample-fwd.fif')
+
+# Inverse operator
+inv = mne.minimum_norm.read_inverse_operator('sample-inv.fif')
+
+# Source estimate
+stc = mne.read_source_estimate('sample')
+
+# Covariance
+cov = mne.read_cov('sample-cov.fif')
+
+# Annotations
+annot = mne.read_annotations('annotations.fif')
+
+# Labels (FreeSurfer ROIs)
+label = mne.read_label('lh.V1.label')
+labels = mne.read_labels_from_annot(subject, parc='aparc', subjects_dir=subjects_dir)
+
+# Trans (head-MRI transform)
+trans = mne.read_trans('sample-trans.fif')
+```