@brainpilot/skills 0.0.6 → 0.0.7

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

@@ -0,0 +1,210 @@
+---
+name: nsd-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the Natural Scenes Dataset (NSD), including data access, BIDS validation, multimodal processing of task-fMRI and structural MRI, stimulus metadata extraction, and QC integration. Triggers include: 'NSD', 'Natural Scenes Dataset', 'process NSD data', 'NSD fMRI', 'visual neuroscience', or any request to run the NSD multimodal pipeline."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - fmri-skill
+  - bids-organizer
+  - claw-shell
+complementary_skills:
+  - brain-visualization
+  - nibabel-skill
+---
+# NSD Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`nsd-skill` is the NeuroClaw orchestration skill for the **Natural Scenes Dataset (NSD)**.
+
+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 via `claw-shell`.
+- Companion scripts in `scripts/` provide reference implementations for BIDS validation, stimulus extraction, and QC.
+
+**Core workflow (never bypassed):**
+1. Identify input NSD data and target modalities.
+2. Generate a **numbered execution plan** clearly stating 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 (`nsd_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| BIDS validation | Validate NSD BIDS structure | `scripts/validate_nsd.py` | Validation report |
+| sMRI processing | Brain extraction, tissue segmentation | `smri-skill` | `smri_output/` derivatives |
+| task-fMRI processing | Visual task GLM, voxel-wise encoding | `fmri-skill` | `fmri_output/` task results |
+| Stimulus extraction | COCO image metadata, annotations | `scripts/extract_nsd_stimulus.py` | Stimulus metadata CSV |
+| QC summary | Per-subject quality control | `scripts/nsd_qc_summary.py` | QC summary + exclusion list |
+
+---
+
+## Dataset Characteristics
+
+- **Cohort**: 8 healthy adults (subj01-subj08)
+- **Scanner**: 7T Siemens MAGNETOM
+- **Resolution**: 1.8mm isotropic voxels
+- **Sessions**: ~30-40 scanning sessions per subject
+- **Total fMRI**: ~30 hours per subject
+- **Stimuli**: ~73,000 natural scene images from COCO dataset
+- **Access**: OSF (Open Science Framework) and Amazon S3
+- **Reference**: Allen et al. (2021), Nature Neuroscience
+
+---
+
+## Supported Modalities
+
+| Modality | Description | Details |
+|---|---|---|
+| T1w | High-resolution structural MRI | 7T anatomical scans |
+| task-fMRI | Visual task fMRI | Natural scene viewing with fixation task |
+| dMRI | Diffusion-weighted imaging | White matter tractography |
+| Retinotopy | Retinotopic mapping | Visual area identification |
+| Eye-tracking | Gaze position data | During image viewing |
+
+---
+
+## NSD Task Paradigms
+
+| Task | Description | Duration |
+|---|---|---|
+| NSD | Natural scene viewing (COCO images) | ~30-40 sessions × ~15 min each |
+| FIXATION | Fixation task during image presentation | Continuous |
+
+---
+
+## COCO Stimulus Metadata
+
+The NSD uses images from the COCO (Common Objects in Context) dataset:
+- ~73,000 unique natural scene images
+- Each image has: 5 captions, 80 object categories, segmentation masks
+- Images are presented for 3 seconds each
+- Subjects perform a fixation task (detect image repeat)
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/validate_nsd.py`
+
+Validates NSD BIDS structure and generates a compliance report.
+
+```bash
+python skills/nsd-skill/scripts/validate_nsd.py \
+  --input /path/to/NSD/bids \
+  --output /path/to/nsd_output/qc/bids_validation.csv
+```
+
+Features:
+- BIDS directory structure validation
+- Subject completeness check (8 subjects)
+- Session count validation (~30-40 sessions per subject)
+- Stimulus file presence verification
+- Missing data identification
+
+---
+
+## Core Workflow (Never Bypassed)
+
+1. Identify user target: full NSD processing, imaging subset, stimulus extraction, or BIDS validation only.
+2. Generate a numbered plan with tools, outputs, runtime, storage, and risks.
+3. Wait for explicit confirmation (`YES` / `execute` / `proceed`).
+4. On confirmation, run BIDS validation using `scripts/validate_nsd.py`.
+5. Delegate to `smri-skill` for structural MRI processing.
+6. Delegate to `fmri-skill` for task-fMRI processing (natural scene viewing).
+7. If stimulus extraction is requested, run `scripts/extract_nsd_stimulus.py`.
+8. If QC summary is requested, run `scripts/nsd_qc_summary.py`.
+9. Save outputs into `nsd_output/`.
+
+---
+
+## Modality Processing Delegation
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w) | `smri-skill` | brain extraction, tissue segmentation, cortical reconstruction | `smri_output/` derivatives |
+| task-fMRI | `fmri-skill` | preprocessing, denoising, voxel-wise encoding | `fmri_output/` task results |
+| dMRI | `fmri-skill` | diffusion preprocessing, tensor metrics | `dwi_output/` metrics |
+
+---
+
+## Standard Output Layout
+
+```
+nsd_output/
+├── bids/                   # BIDS-staged data (or validation report)
+├── smri/                   # Structural MRI derivatives
+├── fmri/                   # Functional MRI derivatives (natural scene viewing)
+├── stimulus/               # COCO stimulus metadata
+├── qc/                     # QC summaries and exclusion lists
+└── logs/                   # Processing logs
+```
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full orchestration when the task only asks for local NSD data validation.
+
+- If the task starts from NSD data already present on disk and only asks for BIDS validation:
+  - Skip the download stage
+  - Default to the narrow path `local NSD discovery -> BIDS validation -> report`
+- In benchmark mode, do not require explicit confirmation before presenting the validation solution.
+
+---
+
+## Safety and Execution Policy
+- No execution before explicit plan confirmation.
+- All execution must be routed via `claw-shell`.
+- Missing dependencies must be resolved by `dependency-planner` before running.
+
+---
+
+## Important Notes and Limitations
+- NSD is a high-resolution 7T dataset; processing requires significant compute resources.
+- 8 subjects with dense repeated measures (~30 hours of fMRI each).
+- Visual neuroscience focus: standard task GLM may not apply; consider voxel-wise encoding models.
+- COCO stimulus metadata is essential for stimulus-response analyses.
+- Cortical surface-based representations using FreeSurfer outputs.
+- `nsd-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end NSD workflow.
+- User asks to process NSD task-fMRI data.
+- User needs BIDS validation for NSD data.
+- User asks to extract NSD stimulus metadata (COCO images, captions, categories).
+- User asks for visual cortex analysis or voxel-wise encoding.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill` → structural MRI preprocessing
+- `fmri-skill` → functional MRI preprocessing and analysis
+- `nibabel-skill` → NIfTI I/O and surface data
+- `bids-organizer` → BIDS validation and organization
+- `brain-visualization` → visualization of derivatives
+- `dependency-planner` → dependency resolution
+- `conda-env-manager` → environment management
+- `claw-shell` → command execution
+
+---
+
+## Reference
+- NSD: https://naturalscenesdataset.org/
+- Allen et al. (2021): A massive 7T fMRI dataset to bridge cognitive neuroscience and artificial intelligence. Nature Neuroscience.
+- COCO: https://cocodataset.org/
+
+Created At: 2026-05-06 13:31 HKT
+Last Updated At: 2026-05-06 13:31 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/nsd-skill/scripts/extract_nsd_stimulus.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Extract NSD stimulus metadata from COCO annotations.
+
+Reads NSD stimulus information (COCO image IDs, captions, categories)
+and produces a merged stimulus metadata table for stimulus-response analyses.
+"""
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+def load_nsd_stimulus_info(stimulus_dir: Path) -> List[Dict]:
+    """Load NSD stimulus info from nsd_stiminfo.tsv or equivalent."""
+    stim_info = []
+    stim_file = stimulus_dir / "nsd_stiminfo.tsv"
+    if stim_file.exists():
+        with open(stim_file, "r", encoding="utf-8") as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            stim_info = list(reader)
+    return stim_info
+
+
+def load_coco_annotations(coco_dir: Path) -> Dict[int, Dict]:
+    """Load COCO annotations (captions + categories) keyed by image_id."""
+    coco_data = {}
+
+    # Load captions
+    captions_file = coco_dir / "annotations" / "captions_train2017.json"
+    if captions_file.exists():
+        with open(captions_file, "r", encoding="utf-8") as f:
+            caps = json.load(f)
+        for ann in caps.get("annotations", []):
+            img_id = ann["image_id"]
+            if img_id not in coco_data:
+                coco_data[img_id] = {"captions": [], "categories": []}
+            coco_data[img_id]["captions"].append(ann["caption"])
+
+    # Load instances (categories)
+    instances_file = coco_dir / "annotations" / "instances_train2017.json"
+    if instances_file.exists():
+        with open(instances_file, "r", encoding="utf-8") as f:
+            instances = json.load(f)
+        # Build category id -> name map
+        cat_map = {c["id"]: c["name"] for c in instances.get("categories", [])}
+        for ann in instances.get("annotations", []):
+            img_id = ann["image_id"]
+            if img_id not in coco_data:
+                coco_data[img_id] = {"captions": [], "categories": []}
+            cat_name = cat_map.get(ann["category_id"], "unknown")
+            if cat_name not in coco_data[img_id]["categories"]:
+                coco_data[img_id]["categories"].append(cat_name)
+
+    return coco_data
+
+
+def load_subject_trials(events_dir: Path, subject: str) -> List[Dict]:
+    """Load trial-level stimulus info from a subject's events files."""
+    trials = []
+    pattern = f"{subject}_task-nsd*_events.tsv"
+    for events_file in sorted(events_dir.glob(pattern)):
+        with open(events_file, "r", encoding="utf-8") as f:
+            reader = csv.DictReader(f, delimiter="\t")
+            for row in reader:
+                row["_source_file"] = events_file.name
+                trials.append(row)
+    return trials
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Extract NSD stimulus metadata from COCO annotations."
+    )
+    parser.add_argument("--nsd-dir", required=True,
+                        help="Path to NSD root directory (BIDS format)")
+    parser.add_argument("--coco-dir",
+                        help="Path to COCO annotations directory (optional)")
+    parser.add_argument("--output", required=True,
+                        help="Output path for stimulus metadata CSV")
+    parser.add_argument("--subject", default=None,
+                        help="Extract for specific subject only (e.g., subj01)")
+    args = parser.parse_args()
+
+    nsd_dir = Path(args.nsd_dir).resolve()
+    if not nsd_dir.exists():
+        print(f"NSD directory not found: {nsd_dir}", file=sys.stderr)
+        return 1
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Load NSD stimulus info
+    stim_info = load_nsd_stimulus_info(nsd_dir)
+    print(f"Loaded {len(stim_info)} stimulus entries from nsd_stiminfo.tsv")
+
+    # Load COCO annotations if available
+    coco_data = {}
+    if args.coco_dir:
+        coco_dir = Path(args.coco_dir).resolve()
+        if coco_dir.exists():
+            coco_data = load_coco_annotations(coco_dir)
+            print(f"Loaded COCO annotations for {len(coco_data)} images")
+
+    # Determine subjects to process
+    if args.subject:
+        subjects = [args.subject]
+    else:
+        subjects = sorted([
+            d.name for d in nsd_dir.glob("sub-*") if d.is_dir()
+        ])
+
+    # Collect trial-level data
+    all_trials = []
+    for subj in subjects:
+        subj_dir = nsd_dir / subj / "func"
+        if not subj_dir.exists():
+            continue
+        trials = load_subject_trials(subj_dir, subj)
+        for t in trials:
+            t["subject_id"] = subj
+        all_trials.extend(trials)
+
+    # Merge stimulus info with trials
+    if stim_info and all_trials:
+        # Build lookup by stimulus index if available
+        stim_lookup = {}
+        for s in stim_info:
+            key = s.get("nsd_id") or s.get("stimulus_id") or s.get("0", "")
+            if key:
+                stim_lookup[str(key)] = s
+
+        for trial in all_trials:
+            stim_idx = trial.get("stimulus_index") or trial.get("stim_id", "")
+            if stim_idx and str(stim_idx) in stim_lookup:
+                for k, v in stim_lookup[str(stim_idx)].items():
+                    if k not in trial:
+                        trial[f"stim_{k}"] = v
+
+    # Enrich with COCO data if available
+    if coco_data and all_trials:
+        for trial in all_trials:
+            coco_id = trial.get("coco_id") or trial.get("stim_coco_id", "")
+            if coco_id and str(coco_id).isdigit():
+                cid = int(coco_id)
+                if cid in coco_data:
+                    trial["coco_captions"] = " | ".join(coco_data[cid]["captions"][:3])
+                    trial["coco_categories"] = ", ".join(coco_data[cid]["categories"])
+
+    # Output
+    if not all_trials and stim_info:
+        # Fallback: output stim_info directly
+        all_trials = stim_info
+
+    if not all_trials:
+        print("[WARN] No stimulus data found.", file=sys.stderr)
+        return 1
+
+    fieldnames = list(all_trials[0].keys())
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(all_trials)
+
+    print(f"Stimulus: {len(all_trials)} trials, {len(fieldnames)} columns -> {output_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/nsd-skill/scripts/nsd_qc_summary.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for NSD processing.
+
+7T-specific QC: tracks session counts, motion metrics, and stimulus coverage.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+def load_confounds(confounds_path: Path) -> Dict[str, float]:
+    """Extract QC metrics from fMRIPrep confounds TSV."""
+    metrics = {
+        "fd_mean": float("nan"),
+        "fd_max": float("nan"),
+        "dvars_mean": 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())
+        if "dvars" in df.columns:
+            dvars = df["dvars"].dropna()
+            metrics["dvars_mean"] = float(dvars.mean())
+    except Exception:
+        pass
+    return metrics
+
+
+def check_exclusion(metrics: Dict[str, float], fd_threshold: float = 0.3) -> List[str]:
+    """Check exclusion criteria for NSD."""
+    reasons = []
+    if not (metrics["fd_mean"] != metrics["fd_mean"]):  # not NaN
+        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 NSD processing."
+    )
+    parser.add_argument("--fmriprep-dir", help="Path to fMRIPrep output directory")
+    parser.add_argument("--nsd-dir", help="Path to NSD BIDS root directory")
+    parser.add_argument("--output", required=True, help="Output path for QC summary CSV")
+    parser.add_argument("--exclude-output", help="Output path for exclusion list CSV")
+    parser.add_argument("--fd-threshold", type=float, default=0.3,
+                        help="FD threshold in mm (default: 0.3, typical for 7T)")
+    args = parser.parse_args()
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Discover subjects
+    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 args.nsd_dir:
+        nsd_dir = Path(args.nsd_dir).resolve()
+        if nsd_dir.exists():
+            for d in nsd_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}
+
+        # Count sessions from BIDS structure
+        if args.nsd_dir:
+            nsd_dir = Path(args.nsd_dir).resolve()
+            subj_dir = nsd_dir / subj
+            if subj_dir.exists():
+                sessions = [d for d in subj_dir.glob("ses-*") if d.is_dir()]
+                metrics["n_sessions"] = len(sessions)
+                func_dir = subj_dir / "func"
+                if func_dir.exists():
+                    bold_runs = list(func_dir.glob("*_task-nsd_bold.nii.gz"))
+                    metrics["n_func_runs"] = len(bold_runs)
+
+        # Extract fMRIPrep confounds metrics
+        if args.fmriprep_dir:
+            confounds_files = list(
+                Path(args.fmriprep_dir).glob(f"{subj}/func/*_desc-confounds_timeseries.tsv")
+            )
+            if confounds_files:
+                # Average across runs
+                fd_means = []
+                fd_maxes = []
+                for cf in confounds_files:
+                    run_metrics = load_confounds(cf)
+                    if run_metrics["fd_mean"] == run_metrics["fd_mean"]:  # not NaN
+                        fd_means.append(run_metrics["fd_mean"])
+                        fd_maxes.append(run_metrics["fd_max"])
+                if fd_means:
+                    metrics["fd_mean"] = sum(fd_means) / len(fd_means)
+                    metrics["fd_max"] = max(fd_maxes)
+                metrics["n_confounds_files"] = len(confounds_files)
+
+        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/nsd-skill/scripts/validate_nsd.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Validate NSD BIDS structure and generate compliance report.
+
+Checks directory structure, subject completeness, session counts,
+and stimulus file presence for the Natural Scenes Dataset.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+# NSD expected subjects
+NSD_SUBJECTS = [f"subj0{i}" for i in range(1, 9)]  # subj01-subj08
+
+# Expected modalities per subject
+EXPECTED_MODALITIES = {
+    "func": ["task-nsd_bold"],
+    "anat": ["T1w"],
+}
+
+
+def validate_subject(subject_dir: Path) -> Dict[str, any]:
+    """Validate a single subject's NSD BIDS structure."""
+    report = {
+        "subject": subject_dir.name,
+        "anat_complete": False,
+        "func_complete": False,
+        "n_sessions": 0,
+        "n_func_runs": 0,
+        "stimulus_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():
+        bold_files = list(func_dir.glob("*_task-nsd_bold.nii.gz"))
+        report["n_func_runs"] = len(bold_files)
+        report["func_complete"] = len(bold_files) > 0
+
+        # Count unique sessions from filenames
+        sessions = set()
+        for f in bold_files:
+            parts = f.name.split("_")
+            for p in parts:
+                if p.startswith("ses-"):
+                    sessions.add(p)
+        report["n_sessions"] = len(sessions)
+
+        if not bold_files:
+            report["missing_files"].append("func/*_task-nsd_bold.nii.gz")
+    else:
+        report["missing_files"].append("func/")
+
+    # Check stimulus files
+    stim_dir = subject_dir / "func"
+    if stim_dir.exists():
+        stim_files = list(stim_dir.glob("*_events.tsv"))
+        report["stimulus_present"] = len(stim_files) > 0
+
+    # Warnings for session count
+    if report["n_sessions"] > 0 and report["n_sessions"] < 30:
+        report["warnings"].append(
+            f"Only {report['n_sessions']} sessions found (expected ~30-40)"
+        )
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate NSD BIDS structure."
+    )
+    parser.add_argument("--input", required=True, help="Path to NSD BIDS directory")
+    parser.add_argument("--output", required=True, help="Output path for validation CSV")
+    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
+
+    # Find subjects
+    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
+
+    # Validate each subject
+    results = []
+    for sub_dir in subjects:
+        report = validate_subject(sub_dir)
+        results.append(report)
+
+    # Write output
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fieldnames = [
+        "subject", "anat_complete", "func_complete",
+        "n_sessions", "n_func_runs", "stimulus_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)
+
+    # Summary
+    complete_subjects = sum(1 for r in results if r["anat_complete"] and r["func_complete"])
+    print(f"\nValidation Summary:")
+    print(f"  Total subjects: {len(results)}")
+    print(f"  Complete (anat + func): {complete_subjects}")
+    print(f"  With T1w: {sum(1 for r in results if r['anat_complete'])}")
+    print(f"  With task-fMRI: {sum(1 for r in results if r['func_complete'])}")
+    print(f"  With stimulus events: {sum(1 for r in results if r['stimulus_present'])}")
+    total_runs = sum(r['n_func_runs'] for r in results)
+    print(f"  Total fMRI runs: {total_runs}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())