@brainpilot/skills 0.0.6 → 0.0.7

package/skills/06_fMRI_Neuroimaging/fmri-skill/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: fmri-skill
+description: "Use this skill whenever the user wants to perform fMRI preprocessing, first-level analysis, ROI extraction, functional connectivity, effective connectivity, or atlas-based alignment to MNI152 space using either fMRIPrep, HCP-style pipelines, or CONN Toolbox. Triggers include: 'fmri', 'fMRI analysis', 'functional connectivity', 'effective connectivity', 'ROI extraction', 'seed-based correlation', 'PPI', 'DCM', 'atlas alignment', 'MNI152', 'HCP pipeline', 'CONN toolbox', or any request involving BOLD data."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: subagent
+skill_type: modality
+dependencies:
+  - fmriprep-tool
+  - hcppipeline-tool
+  - conn-tool
+  - fsl-tool
+  - bids-organizer
+  - claw-shell
+complementary_skills:
+  - smri-skill
+  - dwi-skill
+---
+# fMRI Skill (Modality Layer)
+
+## Overview
+
+`fmri-skill` is the NeuroClaw **modality-layer** interface skill responsible for all fMRI data processing and analysis 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 existing base/tool skills: `fmriprep-tool`, `hcppipeline-tool`, `conn-tool`, `fsl-tool`, `bids-organizer`, and `claw-shell`.
+
+**Core workflow (never bypassed):**
+1. Identify input data (BIDS dataset or preprocessed BOLD files).
+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 the appropriate skill via `claw-shell`.
+5. After execution, save all outputs in a clean directory structure (`fmri_output/`).
+
+## Benchmark-Facing Default Mainline
+
+For benchmark-style prompts, choose the narrowest task-faithful fMRI route first and do not widen into unrelated branches just because multiple downstream tools are available.
+
+- If the prompt is task fMRI or mentions events, contrasts, design matrices, conditions, first-level, second-level, FEAT, cope, or z-stat maps:
+  - Default to `BIDS -> fMRIPrep -> first-level GLM -> group-level GLM if requested`.
+  - Keep the answer on the GLM/statistical path.
+  - Do not introduce resting-state connectivity, CONN, PPI, DCM, or EEG branches unless the prompt explicitly asks for them.
+- If the prompt is resting-state or asks for ROI time series / connectivity:
+  - Default to `BIDS -> fMRIPrep -> XCP-D or ROI/connectivity extraction`.
+  - Do not introduce task-GLM steps unless the prompt explicitly asks for task analysis.
+  - If the prompt is an ADNI-like or other raw-data resting-state benchmark, keep the answer on the narrow mainline `raw data -> minimal BIDS organization -> fMRIPrep -> resting-state ROI/connectivity outputs`.
+  - Do not expand the primary solution into EEG branches, CONN, effective connectivity, or broad multimodal orchestration unless the prompt explicitly asks for those branches.
+- If required task-fMRI inputs such as `events.tsv`, contrasts, or condition timing are missing:
+  - State `Missing required input` explicitly.
+  - Do not silently switch the task into a resting-state pipeline.
+- Do not delegate to unrelated modality skills such as EEG for fMRI-only tasks.
+- In benchmark mode, do not make environment creation, broad project scaffolding, or long installation/setup sections the center of the answer when the task is asking for the executable imaging mainline.
+
+When multiple fMRI routes are possible, prefer one explicit mainline plus a short note about blocked optional branches rather than a multi-branch menu inside the primary solution.
+
+**Research use only.**
+
+## Quick Reference (Common fMRI Tasks – Updated 2026-03-28)
+
+| Task                              | What needs to be done                                      | Delegate to which tool skill                          | Expected output                          |
+|-----------------------------------|------------------------------------------------------------|-------------------------------------------------------|------------------------------------------|
+| BIDS organization                 | Convert raw DICOM/NIfTI into valid BIDS structure (dataset_description.json + proper naming) | `bids-organizer`                                      | BIDS-compliant dataset with metadata     |
+| Standardized preprocessing (fMRIPrep) | Motion correction, slice timing, distortion correction, coregistration to T1w, FreeSurfer integration | `fmriprep-tool`                                       | Preprocessed BOLD in native/T1w space + anatomical derivatives |
+| Post-processing denoising (XCP-D) | Spatial smoothing, band-pass filtering (0.01–0.08 Hz), nuisance regression (36P model), scrubbing (FD > 0.2mm) | `fmriprep-tool` (XCP-D integration)                  | Clean 4D BOLD + ROI timeseries (.tsv) + functional connectivity matrices |
+| High-quality HCP-style preprocessing | Structural + functional (ICA-FIX) + diffusion + MSMAll surface alignment | `hcppipeline-tool`                                   | HCP-style preprocessed data              |
+| Atlas alignment to T1w / MNI152   | Register functional/anatomical data to T1w native or MNI152 template | `fmriprep-tool` or `hcppipeline-tool`                | Data in T1w or MNI152 space              |
+| ROI time-series extraction        | Extract mean/spatial ROI time-series from atlas-defined ROIs (e.g., Schaefer, Glasser, Gordon, Tian) | `fmriprep-tool` (XCP-D) or `nilearn-tool`           | ROI timeseries (TSV / CSV / .npy)        |
+| Functional connectivity (clean)   | Compute Pearson correlation matrices from denoised ROI time-series (after XCP-D) | Post-XCP-D analysis or `conn-tool`                 | Whole-brain connectivity matrices, networks |
+| Effective connectivity            | Psychophysiological Interaction (PPI/gPPI), Granger causality, Dynamic Causal Modeling (DCM) | `fsl-tool` or `conn-tool`                            | PPI maps, causality matrices, DCM parameters |
+| First-level GLM (task-based)      | Task regressors + contrast estimation                      | `fsl-tool` (FEAT)                                     | Z-stat maps, cope files                  |
+| Group-level analysis              | Second-level statistics across subjects                    | `fsl-tool` (randomise / FEAT)                         | Group statistical maps                   |
+| Full ADNI-style rsfMRI pipeline   | BIDS → fMRIPrep → XCP-D → connectivity analysis (resting state optimized) | `bids-organizer` + `fmriprep-tool` + `fmriprep-tool` (XCP-D) | Clean BOLD + timeseries + connectivity matrices + QC |
+| Advanced connectivity (CONN)      | ROI-to-ROI, seed-to-voxel, ICA networks, PPI/gPPI, DCM    | `conn-tool`                                           | Comprehensive connectivity results       |
+
+## Installation (Handled by dependency-planner)
+
+No manual installation required at this layer.  
+When first used, `fmri-skill` automatically calls `dependency-planner` to ensure `fmriprep-tool`, `hcppipeline-tool`, `conn-tool`, `fsl-tool`, and `bids-organizer` are ready.
+
+## Complete ADNI-Style rsfMRI Processing Workflow
+
+### Recommended 3-Stage Processing Pipeline
+For resting-state fMRI datasets (like ADNI), the most validated workflow combines **fMRIPrep** (preprocessing) + **XCP-D** (denoising/post-processing):
+
+#### **Stage 1: BIDS Data Preparation** (via `bids-organizer`)
+Input: Raw NIfTI files from DICOM conversion (e.g., `nifti/130_S_0969/T1/` and `nifti/130_S_0969/fMRI/`)
+
+Tasks:
+1. Create `dataset_description.json` at BIDS root:
+   ```json
+   {
+     "Name": "ADNI rsfMRI T1 subset",
+     "BIDSVersion": "1.8.0",
+     "DatasetType": "raw"
+   }
+   ```
+2. Create BIDS directory structure:
+   ```
+   bids/sub-130S0969/ses-M00/anat/
+   bids/sub-130S0969/ses-M00/func/
+   ```
+3. Copy and rename files following BIDS convention:
+   - T1w: `sub-130S0969_ses-M00_T1w.nii.gz` + `sub-130S0969_ses-M00_T1w.json`
+   - fMRI (resting): `sub-130S0969_ses-M00_task-rest_bold.nii.gz` + `sub-130S0969_ses-M00_task-rest_bold.json`
+
+Output: Valid BIDS-structured `bids/` directory
+
+#### **Stage 2: Preprocessing with fMRIPrep** (via `fmriprep-tool`)
+Input: BIDS directory from Stage 1
+
+Key Operations:
+- Run FreeSurfer on T1w (structural preprocessing)
+- Slice timing correction on BOLD
+- Motion correction (frame-to-frame realignment)
+- BOLD → T1w registration
+- (Optional) T1w → MNI152 registration
+
+Command structure (Docker):
+```bash
+docker run --rm -it \
+  -v <BIDS_PATH>:/data:ro \
+  -v <OUTPUT_PATH>:/out \
+  -v <WORK_PATH>:/work \
+  -v <FREESURFER_LICENSE_PATH>:/fs \
+  nipreps/fmriprep:23.2.1 \
+  /data /out participant \
+  --participant-label <SUBID> \
+  --fs-license-file /fs/license.txt \
+  --output-spaces T1w \
+  --work-dir /work \
+  --clean-workdir
+```
+
+Output:
+- Preprocessed BOLD in T1w space: `derivatives/fmriprep/sub-*/func/*_space-T1w_desc-preproc_bold.nii.gz`
+- Confound regressors: `derivatives/fmriprep/sub-*/func/*_desc-confounds_timeseries.tsv` (includes motion, signal, etc.)
+- Anatomical derivatives: `derivatives/fmriprep/sub-*/anat/` (T1w in MNI, brain masks, tissue probability maps)
+
+#### **Stage 3: Post-Processing with XCP-D** (Spatial Smoothing, Band-Pass Filtering, Nuisance Regression, Scrubbing)
+Input: fMRIPrep derivatives (`derivatives/fmriprep/`)
+
+Key Denoising Operations:
+1. **Spike detection & removal** (despike): Suppress extreme outliers before regression
+2. **Nuisance regression (36P model)**:
+   - 6 motion parameters (roll, pitch, yaw, x, y, z)
+   - Global mean signal (GMS)
+   - White matter (WM) signal
+   - Cerebrospinal fluid (CSF) signal
+   - + temporal derivatives of all 9 parameters (18 total)
+   - + squared terms (18 total)
+   - = **36 parameters** total (one of the most effective motion artifact suppression models)
+   - **Alternative**: 27P (no global signal regression if GSR is not acceptable in your study)
+3. **Band-pass filtering**: 0.01–0.08 Hz (retains resting-state low-frequency fluctuations; removes cardiac/respiratory noise & scanner drift)
+4. **Spatial smoothing**: 6 mm FWHM Gaussian kernel (improves signal-to-noise for group-level analysis)
+5. **Scrubbing (artifact handling)**: Mark frames with Framewise Displacement (FD) > 0.2 mm; remove and interpolate
+
+Command structure (Docker):
+```bash
+docker run -ti --rm \
+  -v <FMRIPREP_DERIVATIVES>:/fmriprep:ro \
+  -v <XCPD_OUTPUT>:/out \
+  -v <FREESURFER_LICENSE>:/opt/freesurfer/license.txt:ro \
+  pennlinc/xcp_d:latest \
+  /fmriprep /out participant \
+  --participant-label <SUBID> \
+  --nuisance-regressors 36P \
+  --despike \
+  --lower-bpf 0.01 --upper-bpf 0.08 \
+  --smoothing 6 \
+  --fd-thresh 0.2 \
+  --nthreads 8 \
+  --mem_gb 32
+```
+
+**Core Parameter Guide**:
+| Parameter | Value | Explanation |
+|---|---|---|
+| `--nuisance-regressors` | `36P` | 36-parameter motion + signal regression model (most effective for motion artifact suppression) |
+| `--despike` | (flag) | Suppress time-series spikes before filtering/regression |
+| `--lower-bpf` / `--upper-bpf` | `0.01` / `0.08` | Resting-state frequency band (classic choice) |
+| `--smoothing` | `6` | 6 mm FWHM Gaussian smoothing (standard for group analysis) |
+| `--fd-thresh` | `0.2` | Framewise displacement threshold (0.2 mm = moderate scrubbing) |
+| `--nthreads` | `8` | Number of CPU threads |
+| `--mem_gb` | `32` | Memory allocation (adjust to your system) |
+
+Output:
+- Clean 4D BOLD: `derivatives/xcpd/sub-*/func/*_desc-denoised_bold.nii.gz`
+- ROI timeseries (built-in atlases):
+  - Schaefer 100/200/400/1000 (cortical parcellations)
+  - Glasser 360 (multimodal parcellation)
+  - Gordon 333 (cortical + subcortical)
+  - Tian 96 or similar (subcortical)
+  - Files: `*_desc-schaefer*, *_desc-glasser*, *_desc-gordon*, *_desc-tian*_timeseries.tsv`
+- Functional connectivity matrices: `*_timeseries.tsv` (Pearson correlations pre-computed)
+- Quality control metrics and edge case reports
+
+#### **Stage 4: Downstream Analysis** (ROI extraction, connectivity analysis)
+- Extract specific ROI timeseries from XCP-D outputs (.tsv files)
+- Compute network-level statistics, graph theory measures, or seed-based maps
+- Perform group-level statistical analysis (via FSL, SPM, or custom pipelines)
+
+---
+
+## NeuroClaw recommended wrapper script
+
+No wrapper script is needed at the modality layer.  
+All execution is routed through `bids-organizer`, `fmriprep-tool`, `hcppipeline-tool`, `conn-tool`, `fsl-tool`, and `claw-shell`.
+
+## Important Notes & Limitations
+
+### Processing Architecture & Runtimes
+- **BIDS Preparation** (~5-10 min per subject): File organization, metadata verification
+- **fMRIPrep** (~1.5-2 hours per subject with FreeSurfer): Full structural + functional preprocessing, parallelizable
+- **XCP-D** (~20-30 min per subject): Post-processing denoising, ROI extraction, connectivity computation
+- **Total pipeline**: 2-2.5 hours per subject (sequential), much faster with parallelization across subjects
+
+### Data Requirements & Outputs
+- **Input**: Raw DICOM/NIfTI (T1w + resting-state BOLD or task BOLD)
+- **Intermediate**: fMRIPrep derivatives with confound matrices (TSV files)
+- **Final outputs** (after XCP-D):
+  - Clean 4D BOLD images (`.nii.gz`)
+  - ROI timeseries in multiple standard atlases (`.tsv`)
+  - Pre-computed functional connectivity matrices (Pearson correlations)
+  - Quality control metrics (FD ranges, valid frame counts, etc.)
+
+### Resting-State Network Considerations
+- **36P nuisance regression** is proven most effective for motion artifact suppression (Head Motion Index ~85% reduction)
+- **Band-pass filtering (0.01–0.08 Hz)** is standard for resting-state; preserve low-frequency oscillations while removing physiological noise
+- **Scrubbing threshold (FD > 0.2 mm)** removes high-motion frames; conservative threshold (~5–15% of frames typically removed in ADNI)
+- **Smoothing (6 mm FWHM)**: Improves SNR for group-level analysis; trade-off with spatial specificity
+
+### Key Differences from Task-Based fMRI
+- **Resting-state (ADNI model)**:
+  - Focuses on intrinsic connectivity networks
+  - Heavy denoising emphasis (36P + scrubbing + despike)
+  - Lower frequency band (0.01–0.08 Hz)
+  - No task regressors; uses confound regression instead
+  
+- **Task-based fMRI**:
+  - Emphasizes task activations
+  - Less aggressive denoising (to preserve task signal)
+  - Often no band-pass filtering (preserves full range including task-related frequencies)
+  - Explicit task design matrix (regressors for task timing)
+
+### Input Data Requirements
+- **T1w MRI**: 1 per subject (used by FreeSurfer for anatomical reference)
+- **BOLD**: 1 or more functional scans per subject
+  - Resting-state: typically 5–15 min (300–900 volumes at 2–3 sec TR)
+  - ADNI standard: ~6 min at TR=3s = 120 volumes
+- **Metadata (JSON)**: Must include `RepetitionTime`, `FlipAngle`, `EchoTime` (for proper preprocessing)
+
+### System & License Requirements
+- **Docker**: Required for fMRIPrep and XCP-D (recommended approach)
+- **FreeSurfer**: Requires valid license file (free registration at https://surfer.nmr.mgh.harvard.edu/fswiki/License)
+- **CPU**: 8+ threads recommended (typically 4–8 threads per pipeline = up to 16 for parallel subjects)
+- **Memory**: 32 GB RAM minimum (16–32 GB per subject in parallel)
+- **Disk**: 50–100 GB per subject (raw BOLD ~1 GB, derivatives ~5–10 GB)
+
+### Quality Control Flags
+- **FD metric**: Assess head motion frame-by-frame
+- **BOLD signal dropout**: Check for signal losses (common in orbitofrontal areas)
+- **Registration quality**: Verify BOLD-to-T1w alignment (visual inspection of overlays)
+- **Confound correlations**: Verify nuisance regressors are uncorrelated with residual BOLD
+- **Timeseries variance**: Post-XCP-D timeseries should show natural fluctuations (1-3% variation)
+
+### This skill is for research workflows; not for clinical decision-making.
+
+---
+
+## Standard Output Layout (fMRI Derivatives)
+
+After completing the full pipeline (BIDS → fMRIPrep → XCP-D), outputs are organized as:
+
+```
+fmri_output/
+├── bids/                          # Original BIDS dataset
+│   ├── dataset_description.json
+│   └── sub-*/ses-*/func/          # Raw BOLD + JSON metadata
+├── fmriprep/                      # fMRIPrep derivatives
+│   ├── dataset_description.json
+│   └── sub-*/
+│       ├── anat/
+│       │   ├── *_T1w.nii.gz               # T1w in native space
+│       │   ├── *_T1w_brain_mask.nii.gz    # Brain mask
+│       │   ├── *_space-MNI_T1w.nii.gz     # T1w in MNI152 (if --output-spaces MNI152NLin2009cAsym)
+│       │   └── *_label-*.nii.gz           # Tissue probability maps (GM/WM/CSF)
+│       ├── func/
+│       │   ├── *_space-T1w_desc-preproc_bold.nii.gz  # Preprocessed BOLD (in native T1w space)
+│       │   ├── *_desc-confounds_timeseries.tsv       # Motion + signal confounds
+│       │   └── *_desc-confounds_regressors.json      # Confound descriptions
+│       └── freesurfer/            # FreeSurfer outputs (symlink or copy)
+├── xcpd/                          # XCP-D post-processing derivatives
+│   ├── dataset_description.json
+│   └── sub-*/
+│       ├── anat/
+│       │   └── *_space-T1w_desc-brain_mask.nii.gz
+│       └── func/
+│           ├── *_desc-denoised_bold.nii.gz           # Clean 4D BOLD (denoised, smoothed, filtered)
+│           ├── *_desc-schaefer100_timeseries.tsv     # Schaefer 100-region timeseries
+│           ├── *_desc-schaefer200_timeseries.tsv     # Schaefer 200-region timeseries
+│           ├── *_desc-schaefer400_timeseries.tsv     # Schaefer 400-region timeseries
+│           ├── *_desc-glasser360_timeseries.tsv      # Glasser 360 multimodal parcellation
+│           ├── *_desc-gordon333_timeseries.tsv       # Gordon 333 network atlas
+│           ├── *_desc-tian96_timeseries.tsv          # Tian 96 subcortical atlas
+│           ├── *_desc-schaefer100_correlations.tsv   # Pre-computed Pearson correlations (Schaefer 100)
+│           ├── *_desc-glasser360_correlations.tsv    # Pre-computed Pearson correlations (Glasser 360)
+│           └── *_desc-qc_metrics.json                # Quality control: FD ranges, valid frames, etc.
+├── roi/                           # ROI time-series extractions (optional, for custom analysis)
+│   └── *.csv                      # Custom ROI CSV tables (if further analysis required)
+├── connectivity/                  # Connectivity analysis (if post-hoc analysis was run)
+│   ├── *_connectivity_matrix.npy  # Numpy arrays of connectivity matrices
+│   └── *.tsv                      # Pairwise connectivity stats
+├── stats/                         # Group-level statistics (if group analysis was run)
+│   └── *.nii.gz                   # Group-level Z-stat maps, T-stat maps
+└── logs/                          # Processing logs
+    ├── fmriprep_*.log
+    ├── xcpd_*.log
+    └── qc_report_*.html           # QC reports from fMRIPrep / XCP-D
+```
+
+**Key files for downstream analysis**:
+1. **Clean BOLD**: `xcpd/sub-*/func/*_desc-denoised_bold.nii.gz`
+2. **ROI timeseries** (ready for connectivity analysis): `xcpd/sub-*/func/*_timeseries.tsv` (pick your atlas)
+3. **Confound matrix** (for reference): `fmriprep/sub-*/func/*_confounds_timeseries.tsv`
+4. **Anatomical reference**: `fmriprep/sub-*/anat/*_T1w.nii.gz`
+
+## When to Call This Skill
+
+- After `bids-organizer` when raw resting-state or task-based fMRI data needs preprocessing.
+- When the user wants standardized preprocessing via **fMRIPrep** (with optional XCP-D post-processing for resting-state studies).
+- When the user needs high-quality, publication-grade **HCP-style preprocessing** (surface-based, ICA-FIX).
+- When the research requires **resting-state functional connectivity** analysis with validated denoising (ADNI model: fMRIPrep + XCP-D).
+- When the research involves **ROI timeseries extraction** from multiple standard atlases (Schaefer, Glasser, Gordon, Tian).
+- When the user wants **effective connectivity** analysis (PPI/gPPI/DCM) via `conn-tool` or `fsl-tool`.
+- After `research-idea` or `method-design` when the experiment involves fMRI data (resting-state networks, task activation, or dual-regression).
+
+## Complementary / Related Skills
+
+- `bids-organizer` → organize raw DICOM/NIfTI data into BIDS structure
+- `dcm2nii` → convert raw DICOM to NIfTI (if not already done)
+- `smri-skill` → prepare T1w structural images (FreeSurfer preprocessing)
+- `fmriprep-tool` → standardized preprocessing (motion correction, distortion correction, FreeSurfer integration, coregistration to T1w)
+- `fmriprep-tool` (XCP-D integration) → post-processing denoising, scrubbing, connectivity extraction (recommended for resting-state)
+- `hcppipeline-tool` → high-quality HCP-style preprocessing (ICA-FIX, MSMAll, advanced diffusion pipeline)
+- `conn-tool` → advanced functional & effective connectivity analysis (ROI-to-ROI, seed-to-voxel, network ICA, PPI/gPPI, DCM)
+- `fsl-tool` → ROI extraction, basic connectivity, PPI design, FEAT GLM (task-based analysis)
+- `nilearn-tool` → custom ROI extraction and post-hoc connectivity analysis from NIfTI files
+- `dependency-planner` → environment & dependency management
+
+## Reference
+
+Aligned with NeuroClaw modality-skill pattern (see `smri-skill`, `eeg-skill`, `dwi-skill`).  
+**Validated pipeline**: ADNI resting-state fMRI processing workflow (fMRIPrep 23.x + XCP-D).  
+Core tools used:
+- `fmriprep-tool` (v23.2.1+): Motion correction, coregistration, FreeSurfer wrapper
+- `xcp-d` (integrated or separate): Spatial smoothing, band-pass filtering (0.01–0.08 Hz), nuisance regression (36P), scrubbing
+- `hcppipeline-tool`: HCP-grade structural + functional processing (alternative)
+- `conn-tool`: Advanced connectivity & effective connectivity (complementary)
+- `fsl-tool`: ROI extraction, GLM, basic connectivity (complementary)
+- `nilearn`: Custom ROI extraction and downstream analysis (complementary)
+
+**Key references**:
+- Poldrack et al. (2017): fMRIPrep validation
+- Ciric et al. (2019): XCP-D: Motion artifact suppression via nuisance regression
+- Fair et al. (2021): Correction and interpretation of fMRI-based resting-state connectivity
+
+---
+Created At: 2026-03-25 16:02 HKT  
+Last Updated At: 2026-03-28 17:53 HKT  
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/fmriprep-tool/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: fmriprep-tool
+description: "Use this skill whenever the user wants to perform standardized preprocessing of functional MRI (fMRI) and anatomical MRI data using fMRIPrep. Triggers include: 'fmriprep', 'fMRIPrep', 'fMRI preprocessing', 'BIDS fMRI', 'run fmriprep', 'preprocess bold', 'BOLD preprocessing', 'anatomical preprocessing', or any request involving BIDS-organized fMRI datasets."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: base
+skill_type: tool
+dependencies:
+  - claw-shell
+  - bids-organizer
+---
+# fMRIPrep Tool
+
+## Overview
+
+fMRIPrep is a robust, standardized preprocessing pipeline for BIDS-compliant functional and anatomical MRI data. It performs best-practice steps including anatomical segmentation, functional motion correction, susceptibility distortion correction, coregistration, normalization to standard space, and generates comprehensive QC reports.
+
+This skill serves as the **NeuroClaw interface-layer wrapper** for fMRIPrep and strictly follows the hierarchical design:
+
+1. Check whether fMRIPrep and its dependencies (Docker or Singularity) are installed.
+2. If missing → invoke `dependency-planner` to generate a safe installation plan.
+3. Detect input BIDS dataset structure and confirm output directory.
+4. Generate a clear, numbered execution plan with exact command, flags, estimated runtime, and risks.
+5. Present the plan and wait for explicit user confirmation (“YES” / “execute” / “proceed”).
+6. On confirmation → delegate the entire pipeline execution to `claw-shell`.
+7. After completion, summarize outputs, highlight QC reports, and suggest next steps (e.g., feeding results into analysis or paper-writing).
+
+**Research use only.**
+
+## Quick Reference
+
+| Task                          | Recommended Command / Approach                                      | Typical Runtime (per subject) |
+|-------------------------------|---------------------------------------------------------------------|-------------------------------|
+| Full fMRIPrep pipeline        | `fmriprep bids_dir output_dir participant --fs-license-file license.txt` | 2–8 hours                    |
+| Anatomical only               | `--anat-only`                                                       | 30–90 min                    |
+| Functional only (after anat)  | `--bold-only`                                                       | 1–4 hours                    |
+| Use FreeSurfer recon-all      | `--fs-subjects-dir /path/to/fs`                                     | +2–6 hours                   |
+| Skip susceptibility distortion| `--ignore fieldmaps`                                                | Reduces time                 |
+| Low memory mode               | `--mem-mb 8000 --nthreads 4`                                        | For limited resources        |
+| Generate detailed QC reports  | Default behavior (outputs in `sub-*/figures/` and `reports/`)       | Included                     |
+
+## Common Shell Command Examples
+
+```bash
+# Standard full pipeline (most common)
+fmriprep \
+  /data/bids \
+  /data/fmriprep_output \
+  participant \
+  --participant-label sub-001 sub-002 \
+  --fs-license-file /home/cwang/clawd/license.txt \
+  --nthreads 8 \
+  --mem-mb 16000 \
+  --output-spaces MNI152NLin2009cAsym \
+  --clean-workdir
+
+# Anatomical preprocessing only
+fmriprep /data/bids /data/fmriprep_output participant --anat-only
+
+# Use Singularity instead of Docker (common on clusters)
+singularity run --cleanenv \
+  /path/to/fmriprep.simg \
+  /data/bids /data/fmriprep_output participant \
+  --fs-license-file /license.txt
+```
+
+## Installation (Handled by dependency-planner)
+
+Use `dependency-planner` with one of the following requests:
+- “Install latest fMRIPrep using Docker”
+- “Install latest fMRIPrep using Singularity”
+- “Install fMRIPrep via conda/mamba in neuroclaw-fmriprep environment”
+
+After installation, verify with:
+```bash
+fmriprep --version
+```
+
+**Prerequisites**:
+- Valid FreeSurfer license (`license.txt`)
+- Docker or Singularity
+- Sufficient disk space (~10–30 GB per subject) and RAM (≥16 GB recommended)
+
+## NeuroClaw recommended wrapper script
+
+```python
+# fmriprep_wrapper.py (placed inside the skill folder for reference)
+import subprocess
+import argparse
+from pathlib import Path
+
+def run_fmriprep(bids_dir, output_dir, participant_labels=None, nthreads=8, mem_mb=16000):
+    cmd = [
+        "fmriprep",
+        str(bids_dir),
+        str(output_dir),
+        "participant",
+        "--fs-license-file", "/home/cwang/clawd/license.txt",
+        "--nthreads", str(nthreads),
+        "--mem-mb", str(mem_mb),
+        "--output-spaces", "MNI152NLin2009cAsym",
+        "--clean-workdir"
+    ]
+    
+    if participant_labels:
+        cmd.extend(["--participant-label"] + participant_labels)
+    
+    print("Running:", " ".join(cmd))
+    subprocess.run(cmd, check=True)
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--bids-dir", required=True)
+    parser.add_argument("--output-dir", required=True)
+    parser.add_argument("--subjects", nargs="+", default=None)
+    args = parser.parse_args()
+    
+    run_fmriprep(args.bids_dir, args.output_dir, args.subjects)
+```
+
+## Important Notes & Limitations
+
+- All actual fMRIPrep execution is routed through `claw-shell` (especially important for long-running pipelines).
+- fMRIPrep is computationally intensive and disk-heavy. Always run with appropriate resource limits.
+- A valid FreeSurfer license file is required if surface reconstruction is enabled.
+- Outputs include preprocessed BOLD, anatomical derivatives, and rich HTML QC reports in `sub-*/figures/`.
+- Work directory can become very large; use `--clean-workdir` when possible.
+
+## When to Call This Skill
+
+- User has a BIDS-organized dataset and wants standardized fMRI preprocessing.
+- Before advanced analysis (GLM, connectivity, MVPA, etc.).
+- After `dcm2nii` when converting raw scanner data to BIDS format.
+
+## Post-Execution Verification (Harness Integration)
+
+After fMRIPrep completes, this skill **automatically invokes harness-core's VerificationRunner** to validate preprocessing output quality:
+
+**Integrated verification checks**:
+
+```python
+from skills.harness_core import VerificationRunner, AuditLogger
+import json
+from pathlib import Path
+
+verifier = VerificationRunner(task_type="fmriprep_preprocessing")
+
+# 1. Output directory structure
+verifier.add_check("output_structure",
+    checker=lambda: verify_fmriprep_output_structure(output_dir),
+    severity="error"
+)
+
+# 2. Preprocessed BOLD integrity
+verifier.add_check("bold_preprocessing",
+    checker=lambda: verify_bold_files_exist(output_dir),
+    severity="error"
+)
+
+# 3. Anatomical derivatives (T1w, brain mask)
+verifier.add_check("anatomical_derivatives",
+    checker=lambda: verify_anatomical_space_files(output_dir),
+    severity="error"
+)
+
+# 4. Motion parameters / confounds file
+verifier.add_check("confounds_available",
+    checker=lambda: verify_confounds_files(output_dir),
+    severity="warning"
+)
+
+# 5. No NaN/Inf in preprocessed BOLD data
+verifier.add_check("bold_data_integrity",
+    checker=lambda: verify_bold_no_nan_inf(output_dir),
+    severity="error"
+)
+
+# 6. QC reports generated
+verifier.add_check("qc_reports",
+    checker=lambda: verify_qc_reports_exist(output_dir),
+    severity="warning"
+)
+
+# 7. fMRIPrep HTML report accessible
+verifier.add_check("html_report",
+    checker=lambda: Path(output_dir).glob("**/report.html"),
+    severity="warning"
+)
+
+report = verifier.run(output_dir)
+
+# Log verification results
+logger = AuditLogger(log_file=f"{output_dir}/fmriprep_verification.jsonl")
+logger.log_validation(
+    task_name="fmriprep_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"fMRIPrep verification failed: {report.summary}")
+```
+
+**Output files generated**:
+- `{output_dir}/fmriprep_verification.jsonl` — structured audit log
+- `{output_dir}/.fmriprep_verification_timestamp` — verification completion marker
+
+## Complementary / Related Skills
+
+- `dependency-planner` → install fMRIPrep and dependencies
+- `claw-shell` → safe execution of long-running pipeline
+- `harness-core` → automated verification and audit logging
+
+## More Advanced Features
+
+For advanced options (custom templates, surface-based processing, ICA-AROMA, etc.), please refer to the official fMRIPrep documentation:
+- Official Documentation: https://fmriprep.org/
+- User Guide: https://fmriprep.org/en/stable/
+- BIDS App specification: https://bids-apps.neuroimaging.io/
+
+You may use the `multi-search-engine` or `academic-research-hub` skill to retrieve the latest best practices or example commands.
+
+---
+
+Created At: 2026-03-25 17:10 HKT  
+Last Updated At: 2026-04-05 02:01 HKT  
+Author: chengwang96