git:20260404.fa7f354 to git:20260505.e9ddd22

5 added, 1 removed. Audit A to A.

---

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