@brainpilot/skills 0.0.6 → 0.0.7

package/skills/06_fMRI_Neuroimaging/ppmi-skill/scripts/extract_ppmi_phenotype.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Extract and merge PPMI phenotype data.
+
+Reads PPMI phenotype files (MDS-UPDRS, MoCA, DAT, demographics)
+and produces a merged phenotype table aligned with imaging subject list.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+COLUMN_MAP = {
+    "subject_id": ["subject", "Subject", "participant_id", "SubID", "PATNO"],
+    "age": ["age", "Age", "Age_at_visit"],
+    "sex": ["sex", "Sex", "Gender"],
+    "diagnosis": ["diagnosis", "Diagnosis", "Group", "COHORT"],
+    "diagnosis_detail": ["diagnosis_detail", "Diagnosis_Detail"],
+    # Motor
+    "mds_updrs_iii": ["MDS_UPDRS_III", "mds_updrs_iii", "NP3TOT"],
+    "mds_updrs_total": ["MDS_UPDRS_Total", "mds_updrs_total"],
+    "h_y": ["H_Y", "h_y", "HoehnYahr"],
+    # Cognitive
+    "moca": ["MoCA", "moca", "MCATOT"],
+    # Olfaction
+    "upsit": ["UPSIT", "upsit", "UPSIT_Total"],
+    # Sleep
+    "rbdsq": ["RBDSQ", "rbdsq"],
+    # DAT imaging
+    "dat_sbr": ["DAT_SBR", "dat_sbr", "CAUDATE_SBR", "PUTAMEN_SBR"],
+    # Biomarkers
+    "csf_abeta": ["CSF_ABeta", "csf_abeta"],
+    "csf_tau": ["CSF_tau", "csf_tau"],
+    "csf_ptau": ["CSF_ptau", "csf_ptau"],
+}
+
+
+def load_csv(path: Path) -> List[Dict[str, str]]:
+    delimiter = "\t" if path.suffix == ".tsv" else ","
+    with open(path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f, delimiter=delimiter)
+        return list(reader)
+
+
+def find_column(row: Dict[str, str], candidates: List[str]) -> Optional[str]:
+    for col in candidates:
+        if col in row:
+            return col
+    return None
+
+
+def extract_phenotype(
+    phenotype_files: List[Path],
+    imaging_ids: Optional[List[str]] = None,
+    columns: Optional[List[str]] = None,
+) -> List[Dict[str, str]]:
+    all_data = []
+    for fpath in phenotype_files:
+        rows = load_csv(fpath)
+        all_data.extend(rows)
+
+    if not all_data:
+        return []
+
+    target_columns = columns if columns else list(COLUMN_MAP.keys())
+    merged = {}
+
+    for row in all_data:
+        subj_col = find_column(row, COLUMN_MAP["subject_id"])
+        if subj_col is None:
+            continue
+        subj_id = row[subj_col].strip()
+        if not subj_id:
+            continue
+
+        if subj_id not in merged:
+            merged[subj_id] = {"subject_id": subj_id}
+
+        for target_col in target_columns:
+            if target_col == "subject_id":
+                continue
+            if target_col in merged[subj_id] and merged[subj_id][target_col]:
+                continue
+            candidates = COLUMN_MAP.get(target_col, [target_col])
+            src_col = find_column(row, candidates)
+            if src_col and row.get(src_col, "").strip():
+                merged[subj_id][target_col] = row[src_col].strip()
+
+    result = list(merged.values())
+    if imaging_ids:
+        imaging_set = set(imaging_ids)
+        result = [r for r in result if r["subject_id"] in imaging_set]
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Extract PPMI phenotype data.")
+    parser.add_argument("--phenotype-files", required=True, nargs="+")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--imaging-ids")
+    parser.add_argument("--columns")
+    args = parser.parse_args()
+
+    phenotype_files = [Path(f).resolve() for f in args.phenotype_files]
+    for f in phenotype_files:
+        if not f.exists():
+            print(f"File not found: {f}", file=sys.stderr)
+            return 1
+
+    imaging_ids = None
+    if args.imaging_ids:
+        id_file = Path(args.imaging_ids).resolve()
+        if id_file.exists():
+            imaging_ids = [l.strip() for l in id_file.read_text().splitlines() if l.strip()]
+
+    columns = None
+    if args.columns:
+        columns = [c.strip() for c in args.columns.split(",")]
+
+    merged = extract_phenotype(phenotype_files, imaging_ids, columns)
+    if not merged:
+        print("[ERROR] No phenotype data extracted.", file=sys.stderr)
+        return 1
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    fieldnames = list(merged[0].keys())
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(merged)
+
+    print(f"Phenotype: {len(merged)} subjects, {len(fieldnames)} columns -> {output_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/ppmi-skill/scripts/ppmi_qc_summary.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for PPMI processing.
+
+PD-specific: tracks diagnostic group and applies appropriate QC criteria.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+def load_confounds(confounds_path: Path) -> Dict[str, float]:
+    metrics = {"fd_mean": float("nan"), "fd_max": float("nan")}
+    try:
+        import pandas as pd
+        df = pd.read_csv(confounds_path, sep="\t")
+        if "framewise_displacement" in df.columns:
+            fd = df["framewise_displacement"].dropna()
+            metrics["fd_mean"] = float(fd.mean())
+            metrics["fd_max"] = float(fd.max())
+    except Exception:
+        pass
+    return metrics
+
+
+def check_exclusion(metrics: Dict[str, float], fd_threshold: float = 0.3) -> List[str]:
+    reasons = []
+    if not (metrics["fd_mean"] != metrics["fd_mean"]):
+        if metrics["fd_mean"] > fd_threshold:
+            reasons.append(f"FD mean {metrics['fd_mean']:.3f} > {fd_threshold}")
+    return reasons
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate QC summaries for PPMI processing.")
+    parser.add_argument("--fmriprep-dir", help="Path to fMRIPrep output directory")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--exclude-output")
+    parser.add_argument("--fd-threshold", type=float, default=0.3)
+    parser.add_argument("--diagnosis-file", help="CSV with subject diagnosis info")
+    args = parser.parse_args()
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    diagnosis_map = {}
+    if args.diagnosis_file:
+        diag_path = Path(args.diagnosis_file).resolve()
+        if diag_path.exists():
+            with open(diag_path, "r", encoding="utf-8") as f:
+                reader = csv.DictReader(f)
+                for row in reader:
+                    subj = row.get("subject_id") or row.get("PATNO", "")
+                    diag = row.get("diagnosis") or row.get("Group") or row.get("COHORT", "")
+                    if subj and diag:
+                        diagnosis_map[subj] = diag
+
+    subjects = set()
+    if args.fmriprep_dir:
+        fmriprep_dir = Path(args.fmriprep_dir).resolve()
+        if fmriprep_dir.exists():
+            for d in fmriprep_dir.glob("sub-*"):
+                if d.is_dir():
+                    subjects.add(d.name)
+
+    if not subjects:
+        print("[WARN] No subjects found.", file=sys.stderr)
+        return 1
+
+    results = []
+    excluded = []
+    for subj in sorted(subjects):
+        metrics = {"subject_id": subj}
+        if diagnosis_map:
+            metrics["diagnosis"] = diagnosis_map.get(subj, "unknown")
+
+        if args.fmriprep_dir:
+            confounds_files = list(Path(args.fmriprep_dir).glob(f"{subj}/func/*_desc-confounds_timeseries.tsv"))
+            if confounds_files:
+                metrics.update(load_confounds(confounds_files[0]))
+
+        exclusion_reasons = check_exclusion(metrics, args.fd_threshold)
+        metrics["excluded"] = len(exclusion_reasons) > 0
+        metrics["exclusion_reasons"] = "; ".join(exclusion_reasons)
+
+        results.append(metrics)
+        if exclusion_reasons:
+            excluded.append({"subject_id": subj, "reasons": "; ".join(exclusion_reasons)})
+
+    if results:
+        fieldnames = list(results[0].keys())
+        with open(output_path, "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=fieldnames)
+            writer.writeheader()
+            writer.writerows(results)
+        print(f"QC: {len(results)} subjects, {len(excluded)} excluded -> {output_path}")
+
+    if args.exclude_output and excluded:
+        exclude_path = Path(args.exclude_output).resolve()
+        exclude_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(exclude_path, "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=["subject_id", "reasons"])
+            writer.writeheader()
+            writer.writerows(excluded)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/ppmi-skill/scripts/validate_ppmi.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Validate PPMI BIDS structure and generate compliance report.
+
+Checks directory structure, diagnostic group completeness, and modality presence.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+def validate_subject(subject_dir: Path) -> Dict[str, any]:
+    report = {
+        "subject": subject_dir.name,
+        "anat_complete": False,
+        "rs_fMRI_present": False,
+        "task_fMRI_present": False,
+        "dwi_present": False,
+        "datscan_present": False,
+        "missing_files": [],
+        "warnings": [],
+    }
+
+    # Check anat
+    anat_dir = subject_dir / "anat"
+    if anat_dir.exists():
+        t1w_files = list(anat_dir.glob("*_T1w.nii.gz"))
+        report["anat_complete"] = len(t1w_files) > 0
+        if not t1w_files:
+            report["missing_files"].append("anat/*_T1w.nii.gz")
+    else:
+        report["missing_files"].append("anat/")
+
+    # Check func
+    func_dir = subject_dir / "func"
+    if func_dir.exists():
+        rest_bold = list(func_dir.glob("*_task-rest_bold.nii.gz"))
+        task_bold = list(func_dir.glob("*_task-*_bold.nii.gz"))
+        task_bold = [f for f in task_bold if "task-rest" not in f.name]
+        report["rs_fMRI_present"] = len(rest_bold) > 0
+        report["task_fMRI_present"] = len(task_bold) > 0
+    else:
+        report["warnings"].append("No func directory")
+
+    # Check dwi
+    dwi_dir = subject_dir / "dwi"
+    if dwi_dir.exists():
+        dwi_files = list(dwi_dir.glob("*_dwi.nii.gz"))
+        report["dwi_present"] = len(dwi_files) > 0
+    else:
+        report["warnings"].append("No dwi directory")
+
+    # Check DaTscan (may be in pet/ or dat/)
+    for dat_dir_name in ["pet", "dat", "spect"]:
+        dat_dir = subject_dir / dat_dir_name
+        if dat_dir.exists():
+            report["datscan_present"] = True
+            break
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate PPMI BIDS structure.")
+    parser.add_argument("--input", required=True)
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    if not input_dir.exists():
+        print(f"Input directory not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    subjects = sorted([d for d in input_dir.glob("sub-*") if d.is_dir()])
+    print(f"Found {len(subjects)} subjects in {input_dir}")
+
+    if not subjects:
+        print("[ERROR] No subjects found.", file=sys.stderr)
+        return 1
+
+    results = []
+    for sub_dir in subjects:
+        report = validate_subject(sub_dir)
+        results.append(report)
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fieldnames = [
+        "subject", "anat_complete", "rs_fMRI_present", "task_fMRI_present",
+        "dwi_present", "datscan_present", "missing_files", "warnings",
+    ]
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        for r in results:
+            r["missing_files"] = "; ".join(r["missing_files"])
+            r["warnings"] = "; ".join(r["warnings"])
+            writer.writerow(r)
+
+    complete = sum(1 for r in results if r["anat_complete"] and r["rs_fMRI_present"])
+    print(f"\nValidation Summary:")
+    print(f"  Total subjects: {len(results)}")
+    print(f"  Complete (anat + rs-fMRI): {complete}")
+    print(f"  With T1w: {sum(1 for r in results if r['anat_complete'])}")
+    print(f"  With rs-fMRI: {sum(1 for r in results if r['rs_fMRI_present'])}")
+    print(f"  With task-fMRI: {sum(1 for r in results if r['task_fMRI_present'])}")
+    print(f"  With dMRI: {sum(1 for r in results if r['dwi_present'])}")
+    print(f"  With DaTscan: {sum(1 for r in results if r['datscan_present'])}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,320 @@
+---
+name: qsiprep-tool
+description: "Use this skill whenever the user wants to run QSIPrep (BIDS App) for diffusion MRI (DWI) preprocessing with best-practice workflows (topup/eddy, denoising/unringing options, susceptibility/motion correction, coregistration/normalization, QC reports) on BIDS datasets. This skill is the NeuroClaw interface-layer wrapper for QSIPrep: it checks installation (Docker/Singularity/conda), generates an execution plan with exact commands and resource estimates, waits for explicit confirmation, then routes all execution through claw-shell."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: base
+skill_type: tool
+dependencies:
+  - claw-shell
+  - bids-organizer
+---
+# QSIPrep Tool (Interface Layer)
+
+## Overview
+QSIPrep is a BIDS-App pipeline for **diffusion MRI (DWI) preprocessing** that emphasizes:
+- Robust distortion/motion/eddy-current correction
+- Interoperable derivatives for downstream modeling (DTI/DKI/CSD, tractography, connectome, etc.)
+- Strong QC reporting (HTML)
+
+This skill is the **NeuroClaw interface-layer wrapper** for QSIPrep and strictly follows the NeuroClaw safety pattern:
+
+1. Check whether QSIPrep is available (preferred: Docker/Singularity image; alternative: conda).
+2. If missing → invoke `dependency-planner` to produce an installation plan.
+3. Verify inputs (must be BIDS-compliant; detect DWI + fieldmaps/reverse-PE b0 if present).
+4. Generate a clear numbered plan with **exact commands**, runtime/resource estimates, and risks.
+5. Wait for explicit user confirmation (“YES” / “execute” / “proceed”).
+6. On confirmation → delegate all commands to `claw-shell`.
+7. Summarize outputs (derivatives paths + QC report location) and suggest next steps.
+
+**Research use only.**
+
+---
+
+## What QSIPrep Typically Does (High-Level)
+- Validates BIDS layout (or skips if requested)
+- Creates brain mask(s)
+- Denoising (optional), Gibbs unringing (optional)
+- Susceptibility distortion correction (e.g., reverse phase-encoded b0 via topup-style approach)
+- Eddy-current + motion correction (FSL eddy family behavior within containerized workflow)
+- Gradient/bvec handling (rotation after motion correction)
+- Coregistration to anatomical (and optionally standard space outputs)
+- Produces derivatives + QC HTML reports
+
+---
+
+## Quick Reference
+
+| Task | Recommended Approach | Typical Output |
+|---|---|---|
+| Standard DWI preprocessing | QSIPrep BIDS-App `participant` | `derivatives/qsiprep/sub-*/dwi/*preproc_dwi.nii.gz` |
+| Multi-subject run | `--participant-label sub-001 sub-002 ...` | per-subject derivatives |
+| HPC / cluster | Singularity `.sif` execution | same derivatives |
+| QC | Default QSIPrep reports | `derivatives/qsiprep/sub-*/figures/*.html` |
+
+Typical runtime (very data-dependent): **~0.5–4+ hours per subject**.
+
+---
+
+## Installation (Handled by `dependency-planner`)
+Preferred: **Docker** (workstations) or **Singularity/Apptainer** (HPC).
+
+Ask `dependency-planner` for one of:
+- “Install Docker and pull latest QSIPrep image”
+- “Install Apptainer/Singularity and pull QSIPrep .sif”
+- “Install QSIPrep via conda (not recommended unless container is unavailable)”
+
+Verification examples:
+```bash
+docker --version
+docker image ls | grep -i qsiprep
+# or
+apptainer --version
+apptainer exec qsiprep.sif qsiprep --version
+```
+
+**FreeSurfer license**: QSIPrep often requires a FreeSurfer license file.
+- Usually passed with: `--fs-license-file /path/to/license.txt`
+- This skill will request it if not provided.
+
+---
+
+## Common Command Templates (Executed via `claw-shell`)
+
+### A) Docker (Recommended on workstations)
+```bash
+# Inputs:
+BIDS_DIR=/data/bids
+OUT_DIR=/data/derivatives
+WORK_DIR=/data/work/qsiprep
+FS_LICENSE=/data/license.txt
+
+mkdir -p "$OUT_DIR" "$WORK_DIR"
+
+docker run --rm -t \
+  -v "$BIDS_DIR":/data:ro \
+  -v "$OUT_DIR":/out \
+  -v "$WORK_DIR":/work \
+  -v "$FS_LICENSE":/opt/freesurfer/license.txt:ro \
+  pennbbl/qsiprep:latest \
+  /data /out participant \
+  --participant-label sub-001 \
+  --work-dir /work \
+  --fs-license-file /opt/freesurfer/license.txt \
+  --nthreads 16 --omp-nthreads 8 --mem-mb 64000
+```
+
+### B) Singularity / Apptainer (Recommended on HPC)
+```bash
+BIDS_DIR=/data/bids
+OUT_DIR=/data/derivatives
+WORK_DIR=/data/work/qsiprep
+FS_LICENSE=/data/license.txt
+IMG=/images/qsiprep.sif
+
+mkdir -p "$OUT_DIR" "$WORK_DIR"
+
+apptainer run --cleanenv \
+  -B "$BIDS_DIR":/data:ro \
+  -B "$OUT_DIR":/out \
+  -B "$WORK_DIR":/work \
+  -B "$FS_LICENSE":/opt/freesurfer/license.txt:ro \
+  "$IMG" \
+  /data /out participant \
+  --participant-label sub-001 \
+  --work-dir /work \
+  --fs-license-file /opt/freesurfer/license.txt \
+  --nthreads 16 --omp-nthreads 8 --mem-mb 64000
+```
+
+> Notes:
+> - Image name (`pennbbl/qsiprep:latest`) should be verified by `dependency-planner` against the latest official docs/releases.
+> - Some flags vary by QSIPrep version; this skill will always generate commands after checking installed version.
+
+---
+
+## NeuroClaw recommended wrapper script (Reference): `qsiprep_wrapper.py`
+
+> This wrapper only *builds and prints* a plan; actual execution must be routed through `claw-shell` by the calling skill.
+
+```python
+# qsiprep_wrapper.py (reference template)
+import argparse
+from pathlib import Path
+from datetime import datetime
+
+def build_qsiprep_cmd(engine, bids_dir, out_dir, work_dir, participant_labels, fs_license, img):
+    labels = " ".join(participant_labels) if participant_labels else ""
+    if engine == "docker":
+        cmd = f"""
+mkdir -p "{out_dir}" "{work_dir}"
+docker run --rm -t \
+  -v "{bids_dir}":/data:ro \
+  -v "{out_dir}":/out \
+  -v "{work_dir}":/work \
+  -v "{fs_license}":/opt/freesurfer/license.txt:ro \
+  {img} \
+  /data /out participant \
+  {"--participant-label " + labels if labels else ""} \
+  --work-dir /work \
+  --fs-license-file /opt/freesurfer/license.txt
+""".strip()
+    else:
+        cmd = f"""
+mkdir -p "{out_dir}" "{work_dir}"
+apptainer run --cleanenv \
+  -B "{bids_dir}":/data:ro \
+  -B "{out_dir}":/out \
+  -B "{work_dir}":/work \
+  -B "{fs_license}":/opt/freesurfer/license.txt:ro \
+  "{img}" \
+  /data /out participant \
+  {"--participant-label " + labels if labels else ""} \
+  --work-dir /work \
+  --fs-license-file /opt/freesurfer/license.txt
+""".strip()
+    return cmd
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser()
+    p.add_argument("--engine", choices=["docker", "apptainer"], required=True)
+    p.add_argument("--bids-dir", required=True)
+    p.add_argument("--out-dir", required=True)
+    p.add_argument("--work-dir", required=True)
+    p.add_argument("--fs-license", required=True)
+    p.add_argument("--img", required=True, help="Docker image (e.g., pennbbl/qsiprep:latest) or .sif path")
+    p.add_argument("--participants", nargs="*", default=None)
+    args = p.parse_args()
+
+    cmd = build_qsiprep_cmd(
+        engine=args.engine,
+        bids_dir=Path(args.bids_dir).resolve(),
+        out_dir=Path(args.out_dir).resolve(),
+        work_dir=Path(args.work_dir).resolve(),
+        participant_labels=args.participants,
+        fs_license=Path(args.fs_license).resolve(),
+        img=args.img
+    )
+
+    tag = f"qsiprep_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+    print("Execution plan (delegate to claw-shell):")
+    print(cmd)
+    print("\nLog tag suggestion:", tag)
+```
+
+---
+
+## Important Notes & Limitations
+- **BIDS input is strongly recommended**. If you only have raw NIfTI/DICOM, use `bids-organizer` (and `dcm2nii`) first.
+- QSIPrep benefits a lot from having **reverse phase-encoded b0 images (AP/PA)** or valid fieldmaps; otherwise distortion correction may be limited.
+- Ensure adequate resources:
+  - RAM commonly **16–64 GB**
+  - Disk: work directory can be large (tens of GB)
+- All execution must go through `claw-shell` due to long runtime and logging requirements.
+- This skill does not replace downstream modeling (DTI/CSD/NODDI). After preprocessing, delegate to:
+  - `dipy-tool` for Python-based metrics/ROI features
+  - MRtrix/FSL-based workflows (future tool skills) for tractography/connectomes
+
+---
+
+## When to Call This Skill
+- User requests “run QSIPrep”, “preprocess DWI with QSIPrep”, “BIDS diffusion preprocessing”, “topup/eddy style pipeline with QC reports”.
+- Before any quantitative diffusion features (FA/MD/tractometry/connectome) are extracted.
+
+## Post-Execution Verification (Harness Integration)
+
+After QSIPrep completes, this skill **automatically invokes harness-core's VerificationRunner** to validate diffusion preprocessing outputs:
+
+**Integrated verification checks**:
+
+```python
+from skills.harness_core import VerificationRunner, AuditLogger
+import nibabel as nib
+import numpy as np
+from pathlib import Path
+
+verifier = VerificationRunner(task_type="qsiprep_diffusion_preprocessing")
+
+# 1. Preprocessed DWI files exist
+verifier.add_check("preprocessed_dwi_exists",
+    checker=lambda: verify_preprocessed_dwi_files(output_dir),
+    severity="error"
+)
+
+# 2. Brain mask generated
+verifier.add_check("brain_mask_generated",
+    checker=lambda: verify_brain_mask_exists(output_dir),
+    severity="error"
+)
+
+# 3. DWI data shape consistent and reasonable
+verifier.add_check("dwi_shape_consistency",
+    checker=lambda: verify_dwi_shape(output_dir),
+    severity="error"
+)
+
+# 4. No NaN/Inf in preprocessed DWI
+verifier.add_check("dwi_data_integrity",
+    checker=lambda: verify_dwi_no_nan_inf(output_dir),
+    severity="error"
+)
+
+# 5. Gradient table preserved and reasonable
+verifier.add_check("gradient_table",
+    checker=lambda: verify_bval_bvec_files(output_dir),
+    severity="warning"
+)
+
+# 6. Motion/susceptibility distortion corrections applied
+verifier.add_check("preprocessing_applied",
+    checker=lambda: verify_preprocessing_flags(output_dir),
+    severity="warning"
+)
+
+# 7. Diffusion metrics (FA/MD) computable from output
+verifier.add_check("diffusion_metric_bounds",
+    checker=lambda: verify_fa_md_bounds(output_dir),
+    severity="warning"
+)
+
+# 8. QC reports generated
+verifier.add_check("qc_reports",
+    checker=lambda: verify_qc_html_reports(output_dir),
+    severity="warning"
+)
+
+report = verifier.run(output_dir)
+
+# Log verification results
+logger = AuditLogger(log_file=f"{output_dir}/qsiprep_verification.jsonl")
+logger.log_validation(
+    task_name="qsiprep_diffusion_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"QSIPrep verification failed: {report.summary}")
+```
+
+**Output files generated**:
+- `{output_dir}/qsiprep_verification.jsonl` — structured audit log
+- `{output_dir}/.qsiprep_verification_timestamp` — completion marker
+
+## Complementary / Related Skills
+
+- `dependency-planner` → install Docker/Apptainer + QSIPrep image
+- `docker-env-manager` → safe Docker operations (pull/run/prune) when needed
+- `claw-shell` → mandatory safe execution layer
+- `harness-core` → automated verification and audit logging
+
+---
+
+## Reference
+- QSIPrep documentation and BIDS App usage (official docs; version-dependent)
+- NeuroClaw interface-layer pattern aligned with `fmriprep-tool` and `hcppipeline-tool`
+
+Created At: 2026-03-26 00:45 HKT
+Last Updated At: 2026-04-05 02:01 HKT
+Author: chengwang96