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

# 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:

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

# 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:

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