MEG Skill (Modality Layer)

Overview

meg-skill is the NeuroClaw modality-layer interface skill responsible for all MEG (magnetoencephalography) 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 implementation code or concrete commands.
• All concrete execution is delegated to MNE-Python (via claw-shell) and companion scripts.
• Companion scripts in scripts/ provide reference implementations for time-frequency analysis and source localization.

Core workflow (never bypassed):

1. Identify input MEG data format (.fif Elekta/Neuromag, .ds CTF, .con KIT/Yokogawa).
2. Ensure T1w structural MRI is available for source localization (via smri-skill if not yet processed).
3. Generate a numbered execution plan clearly stating WHAT needs to be done.
4. Present the full plan, estimated runtime, resource requirements, and risks to the user and wait for explicit confirmation ("YES" / "execute" / "proceed").
5. On confirmation, delegate every step via claw-shell.
6. After execution, save all outputs in a clean directory structure (meg_output/).

Research use only.

---

Quick Reference (Common MEG Tasks)

Task	What needs to be done	Implementation via	Expected output
Load & validation	Read raw MEG, check channel types, info metadata	MNE-Python (mne.io)	Raw object + validation report
Maxwell filtering	Signal-space separation (SSS) for Elekta systems	MNE-Python (mne.preprocessing.maxwell_filter)	Cleaned raw MEG
Filtering	Band-pass, notch (line noise removal at 50/60 Hz)	MNE-Python (raw.filter, raw.notch_filter)	Filtered raw data
Epoching	Segment continuous data around events	MNE-Python (mne.Epochs)	Epoched data
ICA artifact removal	Remove cardiac, ocular, environmental artifacts	MNE-Python (mne.preprocessing.ICA)	Cleaned epochs
Time-frequency analysis	Morlet wavelet multitaper, Hilbert transform	scripts/time_frequency.py	TFR maps (power, ITC)
Source localization	Forward/inverse modeling (MNE, dSPM, beamformer)	MNE-Python + FreeSurfer	Source estimates in brain space
Source-space connectivity	Coherence, PLV, dPLI between source parcels	MNE-Python (mne_connectivity)	Connectivity matrices
Sensor-level connectivity	Coherence, PLV between sensor pairs	MNE-Python	Sensor connectivity
Evoked responses	Average epochs, compute ERPs/ERFs	MNE-Python (epochs.average)	Evoked NIfTI/fif files

---

Supported MEG File Formats

Format	System	Extension	Reader
Elekta/Neuromag	VectorView, TRIUX	.fif	mne.io.read_raw_fif
CTF	CTF MEG systems	.ds	mne.io.read_raw_ctf
KIT/Yokogawa	KIT, Ricoh	.con, .mrk	mne.io.read_raw_kit
BIDS MEG	Any (BIDS format)	.meg.fif	mne.io.read_raw_fif

---

Core Processing Pipeline

Stage 1: Data Loading & Validation

• Load raw MEG data and validate channel types (magnetometers, gradiometers, EEG, EOG, ECG, STIM)
• Check sampling rate, duration, and channel count
• Report bad channels if annotated

Stage 2: Preprocessing

• Maxwell filtering (SSS/tSSS): for Elekta systems, remove environmental noise
• Band-pass filtering: typically 1–100 Hz for sensor-level analysis
• Notch filter: remove power line noise (50 Hz or 60 Hz)
• Downsampling: optional, to reduce computation (e.g., 1000 Hz → 250 Hz)

Stage 3: Artifact Removal (ICA)

• Run ICA (FastICA, Infomax, or Picard)
• Auto-detect and remove cardiac (ECG), ocular (EOG), and muscle artifacts
• Correlate ICA components with ECG/EOG channels

Stage 4: Epoching & Averaging

• Segment around events of interest
• Baseline correction
• Reject bad epochs (amplitude threshold, autoreject)
• Compute evoked responses (ERFs)

Stage 5: Time-Frequency Analysis (via scripts/time_frequency.py)

• Morlet wavelet or multitaper spectral analysis
• Compute power spectral density per frequency band (δ/θ/α/β/γ)
• Inter-trial coherence (ITC)

Stage 6 (Optional): Source Localization

• Requires T1w MRI from smri-skill and FreeSurfer cortical reconstruction
• Compute forward model (BEM or sphere)
• Apply inverse solution (MNE, dSPM, sLORETA, or LCMV beamformer)
• Output source estimates on cortical surface

---

Scripts

scripts/time_frequency.py

Computes time-frequency representations from MEG epochs.

python skills/meg-skill/scripts/time_frequency.py \
  --epochs /path/to/epochs.fif \
  --output /path/to/meg_output/tfr/ \
  --freq-min 1 --freq-max 100 --freq-steps 40 \
  --method morlet \
  --baseline -0.2 0.0

---

Standard Output Layout

meg_output/
├── preprocessed/          # Filtered, cleaned raw MEG
├── epochs/                # Epoched data (.fif)
├── evoked/                # Averaged evoked responses (.fif, .nii.gz)
├── tfr/                   # Time-frequency results
│   ├── power_*.nii.gz
│   └── itc_*.nii.gz
├── source/                # Source estimates (if source localization run)
│   ├── stc_*.lh.stc
│   └── stc_*.rh.stc
├── connectivity/          # Connectivity matrices (if requested)
├── qc/                    # Quality control reports
└── logs/

---

Installation (Handled by dependency-planner)

No manual installation required at this layer. When first used, meg-skill automatically calls dependency-planner to install MNE-Python and dependencies via conda.

---

Important Notes & Limitations

• MEG data is large (hundreds of MB to GB per recording); ensure sufficient disk space.
• Maxwell filtering (SSS) is specific to Elekta/Neuromag systems; CTF and KIT systems use different approaches.
• Source localization requires co-registered T1w MRI and MEG sensor positions (head position indicator coils or digitized head shape).
• MNE-Python is the primary backend; all MEG processing is built on MNE.
• MEG has millisecond temporal resolution but lower spatial resolution than fMRI.
• BIDS-MEG format follows the BIDS extension for MEG: https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/02-magnetoencephalography.html
• This skill is for research workflows; not for clinical decision-making.

---

When to Call This Skill

• When the user provides MEG data (.fif, .ds, .con) and requests preprocessing, artifact removal, or analysis.
• When time-frequency analysis or source localization is needed for MEG data.
• When MEG connectivity analysis (sensor-level or source-level) is requested.
• When eeg-skill handles EEG but the data also includes MEG channels.
• When dataset skills (e.g., Cam-CAN) delegate MEG processing.

---

Complementary / Related Skills

• eeg-skill → EEG processing (MEG and EEG share many MNE-Python tools)
• smri-skill → T1w structural preprocessing (required for source localization)
• freesurfer-tool → cortical reconstruction for source-space analysis
• nibabel-skill → NIfTI I/O for surface/volume data
• brain-visualization → MEG source overlay visualization
• nilearn-tool → post-hoc statistical analysis on source estimates

---

Reference

• MNE-Python: https://mne.tools/
• Gramfort et al. (2013): MEG and EEG data analysis with MNE-Python
• Taulu & Simola (2006): Spatiotemporal signal space separation (SSS)
• BIDS MEG: https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/02-magnetoencephalography.html
• Cam-CAN dataset: https://www.cam-can.org/

Created At: 2026-05-06 12:19 HKT Last Updated At: 2026-05-06 12:19 HKT Author: chengwang96