@brainpilot/skills 0.0.6 → 0.0.8

package/skills/06_fMRI_Neuroimaging/hcpya-skill/scripts/hcpya_qc_summary.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for HCP Young Adult processing.
+
+Combines fMRIPrep confounds and FreeSurfer recon-all metrics
+to produce a unified QC summary with exclusion recommendations.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+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"), "dummy_scans": 0}
+    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 load_freesurfer_qc(fs_dir: Path, subject_id: str) -> Dict[str, float]:
+    """Extract FreeSurfer QC metrics for a subject."""
+    metrics = {
+        "fs_eTIV": float("nan"),
+        "fs_surface_area": float("nan"),
+        "fs_cortical_thickness": float("nan"),
+    }
+    stats_file = fs_dir / subject_id / "stats" / "aseg.stats"
+    if stats_file.exists():
+        try:
+            for line in stats_file.read_text().splitlines():
+                if "EstimatedTotalIntraCranialVol" in line:
+                    parts = line.split(",")
+                    if len(parts) > 4:
+                        metrics["fs_eTIV"] = float(parts[4].strip())
+        except Exception:
+            pass
+    return metrics
+
+
+def check_exclusion(
+    metrics: Dict[str, float],
+    fd_threshold: float = 0.3,
+) -> List[str]:
+    """Check exclusion criteria and return list of reasons."""
+    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 HCP-YA processing."
+    )
+    parser.add_argument("--fmriprep-dir", help="Path to fMRIPrep output directory")
+    parser.add_argument("--freesurfer-dir", help="Path to FreeSurfer output 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="Framewise displacement threshold (default: 0.3 mm)")
+    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.freesurfer_dir:
+        fs_dir = Path(args.freesurfer_dir).resolve()
+        if fs_dir.exists():
+            for d in fs_dir.iterdir():
+                if d.is_dir() and not d.name.startswith("."):
+                    subjects.add(f"sub-{d.name}" if not d.name.startswith("sub-") else d.name)
+
+    if not subjects:
+        print("[WARN] No subjects found. Check directory paths.", file=sys.stderr)
+        return 1
+
+    print(f"Processing {len(subjects)} subjects...")
+
+    # Process each subject
+    results = []
+    excluded = []
+    for subj in sorted(subjects):
+        metrics = {"subject_id": subj}
+
+        # fMRIPrep confounds
+        if args.fmriprep_dir:
+            confounds_files = list(Path(args.fmriprep_dir).glob(f"{subj}/func/*_desc-confounds_timeseries.tsv"))
+            if confounds_files:
+                confounds = load_confounds(confounds_files[0])
+                metrics.update(confounds)
+
+        # FreeSurfer metrics
+        if args.freesurfer_dir:
+            fs_id = subj.replace("sub-", "")
+            fs_metrics = load_freesurfer_qc(Path(args.freesurfer_dir), fs_id)
+            metrics.update(fs_metrics)
+
+        # Check exclusion
+        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)})
+
+    # Write QC summary
+    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"\nQC Summary:")
+        print(f"  Total subjects: {len(results)}")
+        print(f"  Excluded: {len(excluded)}")
+        print(f"  Output: {output_path}")
+
+    # Write exclusion list
+    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)
+        print(f"  Exclusion list: {exclude_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/hcpya-skill/scripts/reorganize_hcpya.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Reorganize HCP Young Adult (HCP1200) native layout to BIDS structure.
+
+Converts HCP-YA directory layout (e.g., 100307/T1w/, 100307/MNINonLinear/)
+to BIDS-compliant structure (sub-100307/anat/, sub-100307/func/).
+"""
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+# HCP-YA task mappings: task folder name -> BIDS task label + full name
+TASK_MAP = {
+    "tfMRI_MOTOR": {"label": "motor", "name": "Motor"},
+    "tfMRI_EMOTION": {"label": "emotion", "name": "Emotion"},
+    "tfMRI_GAMBLING": {"label": "gambling", "name": "Gambling"},
+    "tfMRI_LANGUAGE": {"label": "language", "name": "Language"},
+    "tfMRI_RELATIONAL": {"label": "relational", "name": "Relational"},
+    "tfMRI_SOCIAL": {"label": "social", "name": "Social"},
+    "tfMRI_WM": {"label": "wm", "name": "WorkingMemory"},
+    "rfMRI_REST": {"label": "rest", "name": "RestingState"},
+}
+
+
+def normalize_subject_id(hcp_id: str) -> str:
+    """Convert HCP subject ID to BIDS format."""
+    return f"sub-{hcp_id.strip()}"
+
+
+def find_subjects(input_dir: Path, participant_list: list = None) -> list:
+    """Find HCP subject directories."""
+    subjects = []
+    for d in sorted(input_dir.iterdir()):
+        if d.is_dir() and d.name.isdigit():
+            if participant_list is None or d.name in participant_list:
+                subjects.append(d)
+    return subjects
+
+
+def reorganize_subject(subject_dir: Path, output_dir: Path, dry_run: bool = False) -> dict:
+    """Reorganize a single HCP-YA subject to BIDS."""
+    hcp_id = subject_dir.name
+    bids_id = normalize_subject_id(hcp_id)
+    sub_dir = output_dir / bids_id
+
+    report = {"subject": hcp_id, "files_created": 0, "warnings": []}
+
+    if not dry_run:
+        (sub_dir / "anat").mkdir(parents=True, exist_ok=True)
+        (sub_dir / "func").mkdir(parents=True, exist_ok=True)
+        (sub_dir / "dwi").mkdir(parents=True, exist_ok=True)
+
+    # Structural MRI: T1w and T2w
+    mninonlinear = subject_dir / "MNINonLinear"
+    t1w_src = mninonlinear / "T1w.nii.gz"
+    t2w_src = mninonlinear / "T2w.nii.gz"
+
+    if t1w_src.exists():
+        dst = sub_dir / "anat" / f"{bids_id}_T1w.nii.gz"
+        if not dry_run:
+            shutil.copy2(t1w_src, dst)
+        report["files_created"] += 1
+    else:
+        report["warnings"].append("T1w not found")
+
+    if t2w_src.exists():
+        dst = sub_dir / "anat" / f"{bids_id}_T2w.nii.gz"
+        if not dry_run:
+            shutil.copy2(t2w_src, dst)
+        report["files_created"] += 1
+    else:
+        report["warnings"].append("T2w not found")
+
+    # Functional MRI
+    for task_dir_name, task_info in TASK_MAP.items():
+        task_dir = subject_dir / task_dir_name
+        if not task_dir.exists():
+            task_dir = mninonlinear / "Results" / task_dir_name
+
+        if task_dir.exists():
+            # Look for the main bold file
+            bold_candidates = list(task_dir.glob("*_bold.nii.gz"))
+            if not bold_candidates:
+                bold_candidates = list(task_dir.glob("*.nii.gz"))
+
+            for bold_src in bold_candidates:
+                run_label = "01"
+                bids_task = task_info["label"]
+                dst_name = f"{bids_id}_task-{bids_task}_run-{run_label}_bold.nii.gz"
+                dst = sub_dir / "func" / dst_name
+                if not dry_run:
+                    shutil.copy2(bold_src, dst)
+                report["files_created"] += 1
+
+    # Diffusion MRI
+    dmri_dir = subject_dir / "T1w" / "Diffusion"
+    if dmri_dir.exists():
+        for suffix in ["data.nii.gz", "bval", "bvec"]:
+            src = dmri_dir / suffix
+            if src.exists():
+                bids_suffix = suffix.replace("data.nii.gz", "dwi.nii.gz")
+                dst = sub_dir / "dwi" / f"{bids_id}_{bids_suffix}"
+                if not dry_run:
+                    shutil.copy2(src, dst)
+                report["files_created"] += 1
+
+    return report
+
+
+def create_dataset_description(output_dir: Path, n_subjects: int):
+    """Create BIDS dataset_description.json."""
+    desc = {
+        "Name": "HCP Young Adult (HCP1200)",
+        "BIDSVersion": "1.8.0",
+        "DatasetType": "raw",
+        "License": "HCP Data Use Terms",
+        "Authors": ["Human Connectome Project"],
+        "Acknowledgements": "WU-Minn HCP Consortium",
+        "HowToAcknowledge": "Please cite the Human Connectome Project.",
+        "ReferencesAndLinks": [
+            "https://www.humanconnectome.org/study/hcp-young-adult",
+            "Glasser et al. (2013) NeuroImage"
+        ],
+        "Subjects": n_subjects
+    }
+    with open(output_dir / "dataset_description.json", "w", encoding="utf-8") as f:
+        json.dump(desc, f, indent=2)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Reorganize HCP-YA native layout to BIDS."
+    )
+    parser.add_argument("--input", required=True, help="Path to HCP-YA raw directory")
+    parser.add_argument("--output", required=True, help="Output BIDS directory")
+    parser.add_argument("--participants", help="Text file with subject IDs (one per line)")
+    parser.add_argument("--dry-run", action="store_true", help="Preview without copying")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    output_dir = Path(args.output).resolve()
+
+    if not input_dir.exists():
+        print(f"Input directory not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    # Load participant list
+    participant_list = None
+    if args.participants:
+        p_file = Path(args.participants).resolve()
+        if not p_file.exists():
+            print(f"Participant list not found: {p_file}", file=sys.stderr)
+            return 1
+        participant_list = [line.strip() for line in p_file.read_text().splitlines() if line.strip()]
+        print(f"Subject list: {len(participant_list)} subjects")
+
+    # Find subjects
+    subjects = find_subjects(input_dir, participant_list)
+    print(f"Found {len(subjects)} subject directories in {input_dir}")
+
+    if not subjects:
+        print("No subjects found. Check input directory structure.", file=sys.stderr)
+        return 1
+
+    if not args.dry_run:
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Process each subject
+    total_files = 0
+    all_warnings = []
+    for i, sub_dir in enumerate(subjects):
+        report = reorganize_subject(sub_dir, output_dir, dry_run=args.dry_run)
+        total_files += report["files_created"]
+        if report["warnings"]:
+            all_warnings.extend([f"{report['subject']}: {w}" for w in report["warnings"]])
+        if (i + 1) % 100 == 0 or (i + 1) == len(subjects):
+            print(f"  Processed {i + 1}/{len(subjects)} subjects ({total_files} files)")
+
+    # Create dataset metadata
+    if not args.dry_run:
+        create_dataset_description(output_dir, len(subjects))
+
+    # Summary
+    print(f"\nBIDS Staging Summary:")
+    print(f"  Subjects: {len(subjects)}")
+    print(f"  Files created: {total_files}")
+    print(f"  Output: {output_dir}")
+    if args.dry_run:
+        print("  [DRY RUN - no files were copied]")
+
+    if all_warnings:
+        print(f"\n  Warnings ({len(all_warnings)}):")
+        for w in all_warnings[:20]:
+            print(f"    - {w}")
+        if len(all_warnings) > 20:
+            print(f"    ... and {len(all_warnings) - 20} more")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,198 @@
+---
+name: ixi-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the IXI (Information eXtraction from Images) dataset, including data download, BIDS organization, and multimodal processing of T1w, T2w, and MRA. Triggers include: 'IXI', 'IXI dataset', 'process IXI data', 'IXI MRI', or any request to run the IXI multimodal pipeline."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - bids-organizer
+  - claw-shell
+complementary_skills:
+  - nibabel-skill
+---
+# IXI Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`ixi-skill` is the NeuroClaw orchestration skill for the **IXI (Information eXtraction from Images)** dataset.
+
+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 data reorganization, phenotype extraction, and QC.
+
+**Core workflow (never bypassed):**
+1. Identify input IXI 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 (`ixi_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| Data download | Download IXI from brain-development.org | `claw-shell` | Raw IXI files |
+| BIDS staging | Reorganize IXI native layout to BIDS | `scripts/reorganize_ixi.py` | BIDS-compliant dataset |
+| sMRI processing | Brain extraction, tissue segmentation, cortical reconstruction | `smri-skill` | `smri_output/` derivatives |
+| MRA processing | Vessel enhancement, angiography analysis | `nibabel-skill` | MRA derivatives |
+| QC summary | Per-subject quality control | `scripts/ixi_qc_summary.py` | QC summary + exclusion list |
+
+---
+
+## Dataset Characteristics
+
+- **Cohort**: ~600 healthy subjects
+- **Sites**: 3 London hospitals with different scanners
+  - **Hammersmith Hospital (HH)**: Philips 3T
+  - **Guy's Hospital (Guy)**: Philips 1.5T
+  - **Institute of Psychiatry (IOP)**: GE 1.5T
+- **Modalities**: T1w, T2w, MRA (some subjects also have PD and DTI)
+- **Format**: NIfTI (.nii.gz)
+- **Access**: https://brain-development.org/ixi-dataset/
+
+---
+
+## Supported Modalities
+
+| Modality | Description | Sites |
+|---|---|---|
+| T1w | High-resolution structural MRI | All 3 sites |
+| T2w | T2-weighted structural MRI | All 3 sites |
+| MRA | Magnetic Resonance Angiography | All 3 sites |
+| PD | Proton Density (some subjects) | Selected sites |
+| DTI | Diffusion Tensor Imaging (some subjects) | Selected sites |
+
+---
+
+## Site-Specific Scanner Information
+
+| Site | Scanner | Field Strength | Notes |
+|---|---|---|---|
+| Hammersmith Hospital (HH) | Philips | 3T | Higher resolution, smaller voxel size |
+| Guy's Hospital (Guy) | Philips | 1.5T | Standard resolution |
+| Institute of Psychiatry (IOP) | GE | 1.5T | Standard resolution |
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/reorganize_ixi.py`
+
+Converts IXI native directory structure to BIDS-compliant layout.
+
+```bash
+python skills/ixi-skill/scripts/reorganize_ixi.py \
+  --input /path/to/IXI/raw \
+  --output /path/to/IXI/bids
+```
+
+Features:
+- Subject ID normalization: IXI format (e.g., `IXI002`) to BIDS `sub-IXI002`
+- Site detection from subject ID prefix
+- Modality routing: T1w, T2w, MRA, PD, DTI
+- Sidecar JSON generation with site-specific metadata
+- `dataset_description.json` and `participants.tsv` generation
+- Dry-run mode: `--dry-run` to preview without copying
+
+---
+
+## Core Workflow (Never Bypassed)
+
+1. Identify user target: full IXI processing, imaging subset, or BIDS staging 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 download stage first (if needed).
+5. After download success, run BIDS preparation using `scripts/reorganize_ixi.py`.
+6. Delegate to `smri-skill` for structural MRI processing (T1w, T2w).
+7. Process MRA if requested (vessel enhancement, angiography).
+8. If QC summary is requested, run `scripts/ixi_qc_summary.py`.
+9. Save outputs into `ixi_output/`.
+
+---
+
+## Modality Processing Delegation
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w/T2w) | `smri-skill` | brain extraction, tissue segmentation, cortical reconstruction | `smri_output/` derivatives |
+| MRA | `nibabel-skill` | vessel enhancement, angiography analysis | MRA derivatives |
+| PD | `smri-skill` | proton density analysis | PD derivatives |
+| DTI | `smri-skill` | diffusion tensor metrics | DTI derivatives |
+
+---
+
+## Standard Output Layout
+
+```
+ixi_output/
+├── raw/                    # Downloaded original IXI files
+├── bids/                   # BIDS-staged data
+├── smri/                   # Structural MRI derivatives
+├── mra/                    # MRA derivatives
+├── 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 IXI data staging.
+
+- If the task starts from raw IXI data already present on disk and only asks for BIDS-style staging:
+  - Skip the mandatory download stage
+  - Default to the narrow path `local raw IXI discovery -> BIDS-style staging -> minimal metadata -> validation/report`
+- In benchmark mode, do not require explicit confirmation before presenting the direct staging 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
+- IXI is a multi-site dataset with different scanners; consider site effects in analysis.
+- Site information can be inferred from subject ID prefix (HH, Guy, IOP).
+- MRA data is unique to IXI; vessel analysis requires specialized tools.
+- Some subjects may have missing modalities (PD, DTI).
+- `ixi-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end IXI workflow.
+- User asks to download IXI and run structural MRI processing.
+- User needs BIDS staging for IXI data.
+- User asks for multi-site brain MRI analysis.
+- User asks for MRA vessel analysis.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill` → structural MRI preprocessing
+- `nibabel-skill` → NIfTI I/O and MRA processing
+- `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
+- IXI Dataset: https://brain-development.org/ixi-dataset/
+- Brain-development.org: https://brain-development.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/ixi-skill/scripts/ixi_qc_summary.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for IXI processing.
+
+Multi-site aware: tracks site information and applies site-specific QC criteria.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+# Site mapping
+SITE_MAP = {
+    "HH": {"name": "Hammersmith Hospital", "scanner": "Philips", "field_strength": "3T"},
+    "Guy": {"name": "Guy's Hospital", "scanner": "Philips", "field_strength": "1.5T"},
+    "IOP": {"name": "Institute of Psychiatry", "scanner": "GE", "field_strength": "1.5T"},
+}
+
+
+def detect_site(subject_id: str) -> str:
+    """Detect site from subject ID."""
+    clean_id = subject_id.replace("sub-", "")
+    for prefix in SITE_MAP:
+        if clean_id.startswith(prefix):
+            return prefix
+    return "Unknown"
+
+
+def load_freesurfer_qc(fs_dir: Path, subject_id: str) -> Dict[str, float]:
+    """Extract FreeSurfer QC metrics."""
+    metrics = {"fs_eTIV": float("nan")}
+    stats_file = fs_dir / subject_id / "stats" / "aseg.stats"
+    if stats_file.exists():
+        try:
+            for line in stats_file.read_text().splitlines():
+                if "EstimatedTotalIntraCranialVol" in line:
+                    parts = line.split(",")
+                    if len(parts) > 4:
+                        metrics["fs_eTIV"] = float(parts[4].strip())
+        except Exception:
+            pass
+    return metrics
+
+
+def check_exclusion(metrics: Dict[str, float]) -> List[str]:
+    """Check exclusion criteria."""
+    reasons = []
+    # IXI is healthy subjects; minimal exclusion criteria
+    return reasons
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate QC summaries for IXI processing."
+    )
+    parser.add_argument("--fmriprep-dir", help="Path to fMRIPrep output directory")
+    parser.add_argument("--freesurfer-dir", help="Path to FreeSurfer output 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")
+    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.freesurfer_dir:
+        fs_dir = Path(args.freesurfer_dir).resolve()
+        if fs_dir.exists():
+            for d in fs_dir.iterdir():
+                if d.is_dir() and not d.name.startswith("."):
+                    subjects.add(f"sub-{d.name}" if not d.name.startswith("sub-") else 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}
+
+        # Detect site
+        site = detect_site(subj)
+        site_info = SITE_MAP.get(site, {"name": "Unknown", "scanner": "Unknown", "field_strength": "Unknown"})
+        metrics["site"] = site_info["name"]
+        metrics["scanner"] = site_info["scanner"]
+        metrics["field_strength"] = site_info["field_strength"]
+
+        if args.freesurfer_dir:
+            fs_id = subj.replace("sub-", "")
+            metrics.update(load_freesurfer_qc(Path(args.freesurfer_dir), fs_id))
+
+        exclusion_reasons = check_exclusion(metrics)
+        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)
+
+        # Site summary
+        site_counts = {}
+        for r in results:
+            site = r.get("site", "Unknown")
+            site_counts[site] = site_counts.get(site, 0) + 1
+
+        print(f"QC: {len(results)} subjects, {len(excluded)} excluded -> {output_path}")
+        print(f"  Sites: {site_counts}")
+
+    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())