@brainpilot/skills 0.0.6 → 0.0.7

package/skills/05_EEG_ERP/mne-eeg-tool/scripts/eeg_pipeline_reference.py

@@ -0,0 +1,231 @@
+"""MNE-EEG Pipeline Reference - Core EEG processing functions.
+
+Distilled from the NeuroClaw mne-eeg-tool SKILL.md.
+Agent should consult this script instead of copying from SKILL.md directly.
+
+Functions:
+    load_eeg()                          - Load .set/.edf/.bdf/.fif + validation
+    detect_and_interpolate_bad_channels() - Auto-detect + interpolate noisy channels
+    preprocess_filtering()              - Resample + high-pass + notch + bandpass
+    remove_artifacts()                  - ICA + AutoReject + EOG/ECG regression
+    continuous_data_cleaning()          - Resting-state pipeline (no events)
+    rereference_and_epoch()             - Average reference + epoching + baseline
+    extract_frequency_bands()           - Split into delta/theta/alpha/beta/gamma
+    extract_features()                  - Band power, CSP, Hjorth, sample entropy
+    compute_connectivity()              - PLV, coherence, wPLI
+    extract_erp_features()              - Peak amplitude, latency, AUC
+    compute_alpha_asymmetry()           - Frontal alpha asymmetry (emotion studies)
+    run_microstate_analysis()           - EEG microstates (resting-state)
+    full_eeg_pipeline()                 - One-click end-to-end pipeline
+
+Usage:
+    python skills/mne-eeg-tool/scripts/eeg_pipeline_reference.py --input data.set
+    python skills/mne-eeg-tool/scripts/eeg_pipeline_reference.py --input data.set --resting
+"""
+
+import argparse
+
+import mne
+import numpy as np
+import pandas as pd
+from mne.preprocessing import ICA, find_bad_channels, AutoReject
+from mne.decoding import CSP
+from mne_connectivity import spectral_connectivity_epochs
+import pyentrp.entropy as entropy
+
+
+def load_eeg(raw_path: str):
+    """Load EEG data in any supported format + basic validation."""
+    if raw_path.endswith('.set'):
+        raw = mne.io.read_raw_eeglab(raw_path, preload=True)
+    elif raw_path.endswith(('.edf', '.bdf')):
+        raw = mne.io.read_raw_edf(raw_path, preload=True)
+    elif raw_path.endswith('.fif'):
+        raw = mne.io.read_raw_fif(raw_path, preload=True)
+    else:
+        raw = mne.io.read_raw(raw_path, preload=True)
+    print(f"Loaded: {len(raw.ch_names)} channels, {raw.n_times} samples, SFREQ={raw.info['sfreq']} Hz")
+    return raw
+
+
+def detect_and_interpolate_bad_channels(raw: mne.io.Raw):
+    """Explicit bad-channel detection + interpolation."""
+    bads = find_bad_channels(raw, method='correlation', threshold=0.8)
+    raw.info['bads'] = bads
+    raw.interpolate_bads(reset_bads=True)
+    print(f"Interpolated {len(bads)} bad channels")
+    return raw
+
+
+def preprocess_filtering(raw: mne.io.Raw, target_sfreq: int = 256):
+    """Resample + full filtering pipeline."""
+    raw = raw.copy().resample(target_sfreq)
+    raw.filter(l_freq=0.5, h_freq=40, fir_design='firwin')
+    raw.notch_filter(freqs=50, notch_widths=1)
+    return raw
+
+
+def remove_artifacts(raw: mne.io.Raw):
+    """ICA + AutoReject + EOG/ECG regression (if channels exist)."""
+    ica = ICA(n_components=20, random_state=42, method='fastica')
+    ica.fit(raw)
+    eog_inds, _ = ica.find_bads_eog(raw)
+    muscle_inds, _ = ica.find_bads_muscle(raw)
+    ica.exclude = eog_inds + muscle_inds
+    raw_clean = ica.apply(raw.copy())
+
+    ar = AutoReject()
+    events = mne.make_fixed_length_events(raw_clean, duration=2.0)
+    epochs = mne.Epochs(raw_clean, events, tmin=0, tmax=2.0, preload=True, reject_by_annotation=False)
+    ar.fit(epochs)
+    raw_clean = ar.transform(raw_clean)
+
+    print("Artifact removal (ICA + AutoReject) completed")
+    return raw_clean
+
+
+def continuous_data_cleaning(raw: mne.io.Raw):
+    """Resting-state continuous pipeline (no epoching)."""
+    raw = preprocess_filtering(raw)
+    raw = remove_artifacts(raw)
+    raw = raw.set_eeg_reference('average')
+    print("Continuous resting-state cleaning completed")
+    return raw
+
+
+def rereference_and_epoch(raw_clean: mne.io.Raw, events=None):
+    """Re-reference + epoching + baseline correction."""
+    raw_ref = raw_clean.copy().set_eeg_reference('average')
+    if events is None:
+        events = mne.find_events(raw_ref, stim_channel='STI 014')
+    epochs = mne.Epochs(raw_ref, events, tmin=-0.2, tmax=0.8,
+                        baseline=(None, 0), preload=True,
+                        reject=dict(eeg=150e-6))
+    epochs.save("eeg_output/epoched-epo.fif", overwrite=True)
+    return epochs
+
+
+def extract_frequency_bands(raw: mne.io.Raw, output_dir: str = "eeg_output"):
+    """Extract classic bands and save power."""
+    bands = {'delta': (0.5, 4), 'theta': (4, 8), 'alpha': (8, 13),
+             'beta': (13, 30), 'gamma': (30, 40)}
+    power_dict = {}
+    for name, (l, h) in bands.items():
+        band_raw = raw.copy().filter(l_freq=l, h_freq=h)
+        psd, freqs = mne.time_frequency.psd_array_welch(
+            band_raw.get_data(), sfreq=band_raw.info['sfreq'],
+            fmin=l, fmax=h, n_fft=1024)
+        power = np.mean(psd, axis=1)
+        power_dict[name] = power
+        band_raw.save(f"{output_dir}/band_{name}.fif", overwrite=True)
+    df_power = pd.DataFrame(power_dict, index=raw.ch_names)
+    df_power.to_csv(f"{output_dir}/band_power.csv")
+    return df_power
+
+
+def compute_connectivity(epochs: mne.Epochs, output_dir: str = "eeg_output"):
+    """Functional connectivity (PLV, coherence, wPLI)."""
+    conn = spectral_connectivity_epochs(
+        epochs, method=['plv', 'coh', 'wpli'], mode='multitaper',
+        sfreq=epochs.info['sfreq'], fmin=8, fmax=13, faverage=True)
+    np.savez(f"{output_dir}/connectivity.npz", plv=conn[0], coh=conn[1], wpli=conn[2])
+    print("Connectivity matrices saved")
+    return conn
+
+
+def extract_erp_features(epochs: mne.Epochs, output_dir: str = "eeg_output"):
+    """ERP peak amplitude, latency, AUC."""
+    evokeds = epochs.average()
+    peaks = {}
+    for ch in evokeds.ch_names:
+        data = evokeds.get_data(picks=ch).squeeze()
+        peak_idx = np.argmax(np.abs(data))
+        peaks[ch] = {
+            'peak_amp': data[peak_idx],
+            'peak_latency': evokeds.times[peak_idx],
+            'auc': np.trapz(np.abs(data))
+        }
+    df_erp = pd.DataFrame(peaks).T
+    df_erp.to_csv(f"{output_dir}/erp_features.csv")
+    return df_erp
+
+
+def compute_alpha_asymmetry(raw: mne.io.Raw, output_dir: str = "eeg_output"):
+    """Frontal alpha asymmetry (F4-F3)."""
+    raw_alpha = raw.copy().filter(8, 13)
+    epochs = mne.make_fixed_length_epochs(raw_alpha, duration=2.0, preload=True)
+    left = epochs.get_data(picks=['F3']).mean(axis=2)
+    right = epochs.get_data(picks=['F4']).mean(axis=2)
+    asymmetry = (left - right) / (left + right)
+    np.save(f"{output_dir}/alpha_asymmetry.npy", asymmetry)
+    print("Frontal alpha asymmetry computed")
+    return asymmetry
+
+
+def run_microstate_analysis(raw: mne.io.Raw, output_dir: str = "eeg_output"):
+    """EEG microstate analysis (resting-state)."""
+    from mne_microstates import Microstates
+    ms = Microstates(n_states=4)
+    ms.fit(raw)
+    ms.save(f"{output_dir}/microstates.fif")
+    print("Microstate analysis completed (4 states)")
+    return ms
+
+
+def extract_features(epochs: mne.Epochs, output_dir: str = "eeg_output"):
+    """Core + advanced features: band power, CSP, Hjorth, sample entropy."""
+    psds, freqs = mne.time_frequency.psd_array_multitaper(
+        epochs.get_data(), sfreq=epochs.info['sfreq'])
+    band_power = np.mean(psds[:, :, (freqs >= 8) & (freqs <= 13)], axis=2)
+
+    csp = CSP(n_components=4)
+    csp_features = csp.fit_transform(epochs.get_data(), epochs.events[:, -1])
+
+    hjorth = []
+    sample_entropy = []
+    for trial in epochs.get_data():
+        mobility = np.std(np.diff(trial, axis=1), axis=1) / np.std(trial, axis=1)
+        hjorth.append(mobility)
+        sample_entropy.append([entropy.sample_entropy(ch, 2, 0.2)[0] for ch in trial])
+
+    features = {
+        'band_power': band_power,
+        'csp': csp_features,
+        'hjorth': np.array(hjorth),
+        'sample_entropy': np.array(sample_entropy)
+    }
+    np.savez(f"{output_dir}/features.npz", **features)
+    return features
+
+
+def full_eeg_pipeline(raw_path: str, is_resting_state: bool = False, output_dir: str = "eeg_output"):
+    """One-click full EEG pipeline (supports resting-state flag)."""
+    from pathlib import Path
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+    raw = load_eeg(raw_path)
+    raw = detect_and_interpolate_bad_channels(raw)
+
+    if is_resting_state:
+        raw_clean = continuous_data_cleaning(raw)
+        compute_connectivity(mne.make_fixed_length_epochs(raw_clean, duration=2.0, preload=True), output_dir)
+        run_microstate_analysis(raw_clean, output_dir)
+        compute_alpha_asymmetry(raw_clean, output_dir)
+    else:
+        raw_clean = remove_artifacts(preprocess_filtering(raw))
+        epochs = rereference_and_epoch(raw_clean)
+        extract_features(epochs, output_dir)
+        extract_erp_features(epochs, output_dir)
+
+    extract_frequency_bands(raw_clean, output_dir)
+    print(f"Full EEG Pipeline completed! Outputs in: {output_dir}/")
+    return "Pipeline finished"
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="MNE-EEG Pipeline Reference")
+    parser.add_argument("--input", required=True, help="Path to EEG file (.set/.edf/.bdf/.fif)")
+    parser.add_argument("--resting", action="store_true", help="Use resting-state pipeline")
+    parser.add_argument("--output-dir", default="eeg_output", help="Output directory")
+    args = parser.parse_args()
+    full_eeg_pipeline(args.input, is_resting_state=args.resting, output_dir=args.output_dir)

package/skills/05_EEG_ERP/seed-iv-skill/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: seed-iv-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the SEED-IV (SJTU Emotion EEG Dataset - 4 emotions) dataset, including EEG validation, preprocessing, feature extraction, and emotion classification. Triggers include: 'SEED-IV', 'SEED4', 'emotion EEG', 'EEG emotion recognition', 'process SEED-IV', or any request to run the SEED-IV pipeline."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - eeg-skill
+  - bids-organizer
+  - claw-shell
+complementary_skills:
+  - brain-visualization
+---
+# SEED-IV Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`seed-iv-skill` is the NeuroClaw orchestration skill for the **SEED-IV (SJTU Emotion EEG Dataset - 4 emotions)** dataset, developed by the BCMI Lab at Shanghai Jiao Tong University.
+
+It strictly follows the NeuroClaw hierarchical design principles:
+- This skill **only describes WHAT needs to be done** and **which tool skill to delegate to**.
+- It contains **no implementation code or concrete commands**.
+- All concrete execution is delegated to existing base/tool skills via `claw-shell`.
+- Companion scripts in `scripts/` provide reference implementations for EEG validation, feature extraction, and classification.
+
+**Core workflow (never bypassed):**
+1. Identify input SEED-IV data and target analysis.
+2. Generate a **numbered execution plan** clearly stating WHAT needs to be done and which tool skill will handle each step.
+3. Present the full plan, estimated runtime, resource requirements, and risks to the user and wait for explicit confirmation ("YES" / "execute" / "proceed").
+4. On confirmation, delegate every step to the appropriate skill via `claw-shell`.
+5. After execution, save all outputs in a clean directory structure (`seed_iv_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| EEG validation | Validate SEED-IV BIDS structure | `scripts/validate_seed_iv.py` | Validation report |
+| EEG preprocessing | Filtering, artifact removal, epoching | `eeg-skill` | `eeg_output/` preprocessed EEG |
+| Feature extraction | DE, PSD, connectivity features | `scripts/extract_seed_iv_features.py` | Feature matrices |
+| Emotion classification | 4-class emotion recognition | `scripts/classify_seed_iv.py` | Classification results + accuracy |
+
+---
+
+## Dataset Characteristics
+
+- **Cohort**: 15 healthy subjects
+- **Sessions**: 3 sessions per subject (different days)
+- **Emotions**: 4 classes — happy, sad, fear, neutral
+- **Trials**: 24 trials per session (6 per emotion)
+- **Stimuli**: Short film clips designed to elicit specific emotions
+- **EEG System**: ESI NeuroScan System, 62 channels
+- **Sampling rate**: 1000 Hz (downsampled to 200 Hz commonly)
+- **Reference**: Linked mastoids (M1/M2)
+- **Access**: BCMI Lab (bcmi.sjtu.edu.cn/~seed/)
+- **Format**: MATLAB .mat files (community BIDS conversion available)
+
+---
+
+## Supported Modalities
+
+| Modality | Description | Details |
+|---|---|---|
+| EEG | 62-channel EEG | ESI NeuroScan, 1000 Hz |
+| Eye tracking | Eye movement data | Gaze position, blinks |
+| Physiological | GSR (galvanic skin response) | Skin conductance |
+
+---
+
+## SEED-IV Emotion Labels
+
+| Label | Emotion | Trials per Session |
+|---|---|---|
+| 0 | Neutral | 6 |
+| 1 | Sad | 6 |
+| 2 | Fear | 6 |
+| 3 | Happy | 6 |
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/validate_seed_iv.py`
+
+Validates SEED-IV BIDS structure and generates a compliance report.
+
+```bash
+python skills/seed-iv-skill/scripts/validate_seed_iv.py \
+  --input /path/to/SEED-IV/bids \
+  --output /path/to/seed_iv_output/qc/bids_validation.csv
+```
+
+Features:
+- BIDS directory structure validation
+- Subject/session completeness check (15 subjects × 3 sessions)
+- EEG file presence verification
+- Event file validation (emotion labels)
+
+---
+
+## Core Workflow (Never Bypassed)
+
+1. Identify user target: full SEED-IV pipeline, feature extraction only, or classification only.
+2. Generate a numbered plan with tools, outputs, runtime, storage, and risks.
+3. Wait for explicit confirmation (`YES` / `execute` / `proceed`).
+4. On confirmation, run BIDS validation using `scripts/validate_seed_iv.py`.
+5. Delegate to `eeg-skill` for EEG preprocessing (filtering, artifact removal).
+6. Run `scripts/extract_seed_iv_features.py` for feature extraction (DE, PSD).
+7. Run `scripts/classify_seed_iv.py` for emotion classification.
+8. Save outputs into `seed_iv_output/`.
+
+---
+
+## Standard Output Layout
+
+```
+seed_iv_output/
+├── bids/                   # BIDS-staged data (or validation report)
+├── eeg/                    # Preprocessed EEG derivatives
+├── features/               # Extracted features (DE, PSD, connectivity)
+├── classification/         # Classification results and accuracies
+├── qc/                     # QC summaries
+└── logs/                   # Processing logs
+```
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full orchestration when the task only asks for local SEED-IV data validation.
+
+- If the task starts from SEED-IV data already present on disk and only asks for BIDS validation:
+  - Skip the download stage
+  - Default to the narrow path `local SEED-IV discovery -> BIDS validation -> report`
+- In benchmark mode, do not require explicit confirmation before presenting the validation solution.
+
+---
+
+## Safety and Execution Policy
+- No execution before explicit plan confirmation.
+- All execution must be routed via `claw-shell`.
+- Missing dependencies must be resolved by `dependency-planner` before running.
+
+---
+
+## Important Notes and Limitations
+- SEED-IV is a relatively small dataset (15 subjects); cross-subject generalization is challenging.
+- 62-channel EEG provides rich spatial information for source localization.
+- Differential Entropy (DE) features are the most commonly used for SEED-IV classification.
+- Session-level normalization is recommended to handle inter-session variability.
+- `seed-iv-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end SEED-IV workflow.
+- User asks to process SEED-IV EEG data.
+- User needs BIDS validation for SEED-IV data.
+- User asks for EEG-based emotion recognition analysis.
+- User asks to extract DE or PSD features from SEED-IV.
+
+---
+
+## Complementary / Related Skills
+- `eeg-skill` → EEG preprocessing and feature extraction
+- `bids-organizer` → BIDS validation and organization
+- `brain-visualization` → visualization of derivatives
+- `dependency-planner` → dependency resolution
+- `conda-env-manager` → environment management
+- `claw-shell` → command execution
+
+---
+
+## Reference
+- SEED-IV: https://bcmi.sjtu.edu.cn/~seed/
+- BCMI Lab, Shanghai Jiao Tong University
+- Zheng & Lu (2015): Investigating Critical Frequency Bands and Channels for EEG-based Emotion Recognition with Deep Neural Networks. IEEE Trans. Autonomous Mental Development.
+
+Created At: 2026-05-06 14:21 HKT
+Last Updated At: 2026-05-06 14:21 HKT
+Author: chengwang96

package/skills/05_EEG_ERP/seed-iv-skill/scripts/classify_seed_iv.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Classify emotions from SEED-IV features.
+
+Supports SVM, Random Forest, and Leave-One-Subject-Out cross-validation.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+
+def load_features(features_path: Path) -> Tuple[np.ndarray, np.ndarray, List[str]]:
+    """Load features and labels from CSV."""
+    import pandas as pd
+    df = pd.read_csv(features_path)
+
+    # Find label column
+    label_col = None
+    for col in ["emotion", "label", "emotion_label"]:
+        if col in df.columns:
+            label_col = col
+            break
+
+    if label_col is None:
+        raise ValueError("No emotion label column found")
+
+    # Find feature columns
+    feature_cols = [c for c in df.columns if c.startswith("ch") and "_" in c]
+
+    X = df[feature_cols].values.astype(float)
+    y = df[label_col].values.astype(int)
+    subjects = df["subject"].tolist() if "subject" in df.columns else [f"sub-{i}" for i in range(len(y))]
+
+    return X, y, subjects
+
+
+def classify_svm(X: np.ndarray, y: np.ndarray, subjects: List[str]) -> Dict:
+    """SVM classification with Leave-One-Subject-Out CV."""
+    from sklearn.svm import SVC
+    from sklearn.preprocessing import StandardScaler
+    from sklearn.model_selection import LeaveOneGroupOut
+
+    scaler = StandardScaler()
+    logo = LeaveOneGroupOut()
+    y_pred_all = []
+    y_true_all = []
+
+    for train_idx, test_idx in logo.split(X, y, subjects):
+        X_train = scaler.fit_transform(X[train_idx])
+        X_test = scaler.transform(X[test_idx])
+        svm = SVC(kernel="rbf", C=1.0, gamma="scale")
+        svm.fit(X_train, y[train_idx])
+        y_pred_all.extend(svm.predict(X_test))
+        y_true_all.extend(y[test_idx])
+
+    y_pred_all = np.array(y_pred_all)
+    y_true_all = np.array(y_true_all)
+    accuracy = np.mean(y_pred_all == y_true_all)
+
+    # Per-class metrics
+    classes = np.unique(y_true_all)
+    per_class = {}
+    for cls in classes:
+        mask = y_true_all == cls
+        per_class[int(cls)] = {
+            "accuracy": float(np.mean(y_pred_all[mask] == cls)),
+            "n_samples": int(mask.sum()),
+        }
+
+    return {
+        "method": "SVM (RBF)",
+        "cv": "Leave-One-Subject-Out",
+        "accuracy": float(accuracy),
+        "n_subjects": len(set(subjects)),
+        "n_samples": len(y_true_all),
+        "per_class": per_class,
+    }
+
+
+def classify_rf(X: np.ndarray, y: np.ndarray, subjects: List[str]) -> Dict:
+    """Random Forest classification with Leave-One-Subject-Out CV."""
+    from sklearn.ensemble import RandomForestClassifier
+    from sklearn.preprocessing import StandardScaler
+    from sklearn.model_selection import LeaveOneGroupOut
+
+    scaler = StandardScaler()
+    logo = LeaveOneGroupOut()
+    y_pred_all = []
+    y_true_all = []
+
+    for train_idx, test_idx in logo.split(X, y, subjects):
+        X_train = scaler.fit_transform(X[train_idx])
+        X_test = scaler.transform(X[test_idx])
+        rf = RandomForestClassifier(n_estimators=100, random_state=42)
+        rf.fit(X_train, y[train_idx])
+        y_pred_all.extend(rf.predict(X_test))
+        y_true_all.extend(y[test_idx])
+
+    y_pred_all = np.array(y_pred_all)
+    y_true_all = np.array(y_true_all)
+    accuracy = np.mean(y_pred_all == y_true_all)
+
+    return {
+        "method": "Random Forest (100 trees)",
+        "cv": "Leave-One-Subject-Out",
+        "accuracy": float(accuracy),
+        "n_subjects": len(set(subjects)),
+        "n_samples": len(y_true_all),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Classify SEED-IV emotions.")
+    parser.add_argument("--input", required=True, help="Path to features CSV")
+    parser.add_argument("--output", required=True, help="Output path for results")
+    parser.add_argument("--method", choices=["svm", "rf", "both"], default="both",
+                        help="Classification method")
+    args = parser.parse_args()
+
+    input_path = Path(args.input).resolve()
+    if not input_path.exists():
+        print(f"Input file not found: {input_path}", file=sys.stderr)
+        return 1
+
+    X, y, subjects = load_features(input_path)
+    print(f"Loaded {len(y)} samples, {len(set(y))} classes, {len(set(subjects))} subjects")
+
+    results = []
+    if args.method in ("svm", "both"):
+        svm_result = classify_svm(X, y, subjects)
+        results.append(svm_result)
+        print(f"SVM accuracy: {svm_result['accuracy']:.4f}")
+
+    if args.method in ("rf", "both"):
+        rf_result = classify_rf(X, y, subjects)
+        results.append(rf_result)
+        print(f"RF accuracy: {rf_result['accuracy']:.4f}")
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        import json
+        json.dump(results, f, indent=2, default=str)
+
+    print(f"Results saved to {output_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())