EEG Skill (Modality Layer)

Overview

eeg-skill is the NeuroClaw modality-layer interface skill responsible for all EEG data processing tasks. 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 full implementation code.
• All concrete execution (MNE-Python calls, torchaudio, scipy, file I/O, etc.) is delegated to the dedicated base/tool skill mne-eeg-tool.
• Waveform-to-spectrogram conversion uses torchaudio.transforms.MelSpectrogram.
• Frequency-band energy extraction uses continuous wavelet transform (scipy.signal.cwt with morlet2 wavelet).

Core workflow (never bypassed):

1. Identify the user-provided EEG files (BIDS, .set, .edf, .bdf, .fif, etc.).
2. Generate a numbered execution plan that clearly states 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 mne-eeg-tool via claw-shell.
5. After execution, save all outputs in a clean directory structure (eeg_output/).

Research use only — outputs are for scientific analysis only.

Quick Reference (Common EEG Tasks – Updated 2026-03-25)

Task	What needs to be done	Delegate to which tool skill	Expected output
Load & basic validation	Read raw EEG + channel locations + events + validation	claw-shell (via mne-eeg-tool)	Validation report + raw object
Bad-channel detection & interpolation	Auto-detect + interpolate noisy channels	claw-shell (via mne-eeg-tool)	Cleaned raw data
Downsampling + filtering	Resample, high-pass, notch, bandpass filtering	claw-shell (via mne-eeg-tool)	Filtered .fif files
Artifact removal	ICA + AutoReject + EOG/ECG regression	claw-shell (via mne-eeg-tool)	Cleaned data
Continuous data cleaning	Resting-state pipeline (no events)	claw-shell (via mne-eeg-tool)	Cleaned continuous data
Re-referencing & epoching	Average reference (CAR) / REST + epoching + baseline correction	claw-shell (via mne-eeg-tool)	Epoched .fif files
Waveform to Mel-Spectrogram	Convert raw waveform to Mel spectrogram using torchaudio	claw-shell (via mne-eeg-tool)	Mel-spectrogram tensors (.pt)
Frequency-band energy extraction	Extract δ/θ/α/β/γ band energy using CWT with morlet2 wavelet	claw-shell (via mne-eeg-tool)	Per-band power matrices (CSV / .npy)
Feature extraction (core)	Band power, CSP, Hjorth, sample entropy	claw-shell (via mne-eeg-tool)	Feature matrices (CSV / .npy / .npz)
Advanced features	Functional connectivity, ERP peaks/latency/AUC, frontal alpha asymmetry, microstates	claw-shell (via mne-eeg-tool)	Connectivity matrices, ERP CSV, asymmetry .npy, microstates .fif
Full end-to-end pipeline	Any combination of the above for BCI, emotion, epilepsy, fatigue, etc.	claw-shell + dependency-planner	Complete processed dataset + QC report

Installation (Handled by dependency-planner)

No manual installation required. When first used, eeg-skill automatically calls dependency-planner to create the isolated neuroclaw-eeg conda environment containing MNE-Python, torchaudio, scipy, and all required packages.

NeuroClaw recommended wrapper script

# Example snippets (for reference in mne-eeg-tool implementation)

# 1. Waveform to Mel-Spectrogram
import torch
import torchaudio.transforms as T

mel_spec = T.MelSpectrogram(
    sample_rate=256,      # Adjust according to your EEG sampling rate
    n_fft=1024,
    hop_length=256,
    n_mels=128,
    f_min=0.5,
    f_max=60.0            # Common EEG frequency range
)
spectrogram = mel_spec(waveform)   # waveform shape: (channels, time)

# 2. Frequency-band energy extraction using CWT + morlet2
import numpy as np
from scipy.signal import cwt, morlet2

def extract_band_power(signal, fs=256):
    widths = np.arange(1, 128)  # Adjust according to frequency range
    cwt_matrix = cwt(signal, morlet2, widths)

    # Example: extract delta (0.5-4 Hz), theta (4-8 Hz), alpha (8-13 Hz), beta (13-30 Hz), gamma (30-60 Hz)
    delta_power = np.mean(np.abs(cwt_matrix[low_idx:high_idx])**2, axis=0)
    # ... similar processing for other bands
    return band_powers

Important Notes & Limitations

• This SKILL.md contains only high-level task descriptions and delegation instructions.
• Waveform-to-spectrogram conversion is handled by torchaudio.transforms.MelSpectrogram.
• Frequency-band energy extraction is performed via continuous wavelet transform (scipy.signal.cwt + morlet2 wavelet).
• Long-running operations (ICA on long recordings, CWT on high-density data, connectivity matrices, microstate analysis) are automatically routed to background mode in the claw tmux session.
• Execution begins only after explicit user confirmation of the full numbered plan.
• All outputs are saved in ./eeg_output/ with clear subfolders (raw/, filtered/, epoched/, features/, spectrograms/, etc.).

When to Call This Skill

• The user provides raw or partially processed EEG data and requests preprocessing, Mel-spectrogram conversion, frequency-band energy extraction, feature engineering, or a full pipeline.
• After research-idea or method-design when the experiment involves EEG data.

Post-Execution Verification (Harness Integration)

After EEG processing completes, this skill automatically invokes harness-core's VerificationRunner to validate preprocessed data quality:

Integrated verification checks:

from skills.harness_core import VerificationRunner, AuditLogger
import numpy as np
import mne

verifier = VerificationRunner(task_type="eeg_preprocessing")

# 1. EEG data file exists and is readable
verifier.add_check("eeg_file_integrity",
    checker=lambda: verify_eeg_file_readable(output_dir),
    severity="error"
)

# 2. Channel count matches expected
verifier.add_check("channel_count",
    checker=lambda: verify_expected_channels(output_dir, expected_count=64),
    severity="warning"
)

# 3. No excessive bad segments (after artifact removal)
verifier.add_check("artifact_removal_success",
    checker=lambda: verify_bad_segments_removed(output_dir, max_pct=5),
    severity="warning"
)

# 4. Data range plausible (not clipped or saturated)
verifier.add_check("data_range_plausible",
    checker=lambda: verify_data_range(output_dir, min_range=-500, max_range=500),
    severity="error"
)

# 5. No NaN/Inf values in preprocessed data
verifier.add_check("no_nan_inf",
    checker=lambda: verify_no_nan_inf(output_dir),
    severity="error"
)

# 6. Frequency spectrum reasonable (no DC offset, reasonable content)
verifier.add_check("frequency_spectrum",
    checker=lambda: verify_frequency_spectrum(output_dir),
    severity="warning"
)

# 7. Epoching statistics (if applicable)
verifier.add_check("epoch_statistics",
    checker=lambda: verify_epoch_count_and_length(output_dir),
    severity="warning"
)

# 8. Feature extraction output dimensions
verifier.add_check("feature_matrix_shape",
    checker=lambda: verify_feature_matrix_shape(output_dir),
    severity="warning"
)

report = verifier.run(output_dir)

# Log verification results
logger = AuditLogger(log_file=f"{output_dir}/eeg_verification.jsonl")
logger.log_validation(
    task_name="eeg_preprocessing",
    checks_passed=len([r for r in report.results if r.passed]),
    checks_failed=len([r for r in report.results if not r.passed]),
    warnings=len([r for r in report.results if r.severity == "warning" and not r.passed]),
    report_summary=report.to_dict()
)

if report.failed:
    raise ValueError(f"EEG preprocessing verification failed: {report.summary}")

Output files generated:

• {output_dir}/eeg_verification.jsonl — structured audit log
• {output_dir}/.eeg_verification_timestamp — completion marker

Complementary / Related Skills

• dependency-planner + conda-env-manager → environment and package installation (MNE-Python + torchaudio + scipy)
• mne-eeg-tool → base/tool layer that contains all specific implementation code
• harness-core → automated verification and audit logging

Reference

Aligned with NeuroClaw modality-skill pattern (see freesurfer-tool, wmh-segmentation, etc.). Core libraries: MNE-Python (main), torchaudio.transforms.MelSpectrogram (waveform to spectrogram), scipy.signal.cwt + morlet2 (frequency band energy extraction).

---

Created At: 2026-03-25 16:00 HKT Last Updated At: 2026-04-05 02:01 HKT Author: chengwang96