Eeg Skill

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)

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