@brainpilot/skills 0.0.6 → 0.0.7

package/skills/06_fMRI_Neuroimaging/bold5000-skill/scripts/bold5000_qc_summary.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for BOLD5000."""
+import argparse
+import sys
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+try:
+    import pandas as pd
+except ImportError:
+    print("Error: pandas is required.", file=sys.stderr)
+    sys.exit(1)
+
+
+def detect_delimiter(file_path: Path) -> str:
+    with open(file_path, "r", encoding="utf-8") as f:
+        return "\t" if "\t" in f.readline() else ","
+
+
+def collect_fmriprep_qc(fmriprep_dir: Path) -> Dict[str, Dict[str, float]]:
+    qc = {}
+    for confounds_file in fmriprep_dir.rglob("**/*_desc-confounds_timeseries.tsv"):
+        subject_id = next((p for p in confounds_file.parts if p.startswith("sub-")), None)
+        if not subject_id:
+            continue
+        try:
+            df = pd.read_csv(confounds_file, sep=detect_delimiter(confounds_file), low_memory=False)
+        except Exception:
+            continue
+        fd_col = next((c for c in ["framewise_displacement", "fd", "FD"] if c in df.columns), None)
+        if fd_col:
+            fd = pd.to_numeric(df[fd_col], errors="coerce").dropna()
+            if len(fd) > 0:
+                metrics = {"mean_fd": float(fd.mean()), "max_fd": float(fd.max()), "n_volumes": len(df)}
+                if subject_id in qc:
+                    qc[subject_id]["mean_fd"] = max(qc[subject_id].get("mean_fd", 0), metrics["mean_fd"])
+                    qc[subject_id]["max_fd"] = max(qc[subject_id].get("max_fd", 0), metrics["max_fd"])
+                    qc[subject_id]["n_volumes"] = qc[subject_id].get("n_volumes", 0) + metrics["n_volumes"]
+                else:
+                    qc[subject_id] = metrics
+    return qc
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate BOLD5000 QC summaries.")
+    parser.add_argument("--fmriprep-dir", help="Path to fMRIPrep 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="Mean FD threshold (default: 0.3)")
+    parser.add_argument("--max-fd-threshold", type=float, default=5.0, help="Max FD threshold (default: 5.0)")
+    args = parser.parse_args()
+
+    fmriprep_qc = {}
+    if args.fmriprep_dir:
+        fp_dir = Path(args.fmriprep_dir).resolve()
+        if fp_dir.exists():
+            print(f"Collecting fMRIPrep QC from {fp_dir}...")
+            fmriprep_qc = collect_fmriprep_qc(fp_dir)
+            print(f"  Found {len(fmriprep_qc)} subjects")
+
+    if not fmriprep_qc:
+        print("[ERROR] No QC data collected.", file=sys.stderr)
+        return 1
+
+    rows = []
+    excluded = []
+    for sub_id in sorted(fmriprep_qc.keys()):
+        fp = fmriprep_qc[sub_id]
+        reasons = []
+        if fp.get("mean_fd", 0) > args.fd_threshold:
+            reasons.append(f"mean_fd={fp['mean_fd']:.3f}>{args.fd_threshold}")
+        if fp.get("max_fd", 0) > args.max_fd_threshold:
+            reasons.append(f"max_fd={fp['max_fd']:.3f}>{args.max_fd_threshold}")
+        row = {"subject_id": sub_id, "mean_fd": fp.get("mean_fd"), "max_fd": fp.get("max_fd"), "n_volumes": fp.get("n_volumes"), "exclude": bool(reasons), "exclude_reasons": "; ".join(reasons)}
+        if reasons:
+            excluded.append(sub_id)
+        rows.append(row)
+
+    summary_df = pd.DataFrame(rows)
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    summary_df.to_csv(output_path, index=False)
+    print(f"\nQC Summary: {len(summary_df)} subjects -> {output_path}")
+    print(f"  Excluded: {len(excluded)} / {len(summary_df)} ({100*len(excluded)/max(len(summary_df),1):.1f}%)")
+
+    if args.exclude_output:
+        exclude_path = Path(args.exclude_output).resolve()
+        exclude_path.parent.mkdir(parents=True, exist_ok=True)
+        summary_df[summary_df["exclude"] == True][["subject_id", "exclude_reasons"]].to_csv(exclude_path, index=False)
+        print(f"  Exclusion list: {exclude_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/bold5000-skill/scripts/extract_bold5000_stimulus.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Extract and organize BOLD5000 stimulus metadata for downstream analysis."""
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+def extract_stimulus_metadata(stimulus_dir: Path, events_dir: Path = None) -> List[Dict[str, str]]:
+    """Extract stimulus metadata from BOLD5000 stimulus files."""
+    metadata = []
+
+    # Look for stimulus images
+    image_extensions = {".jpg", ".jpeg", ".png", ".bmp", ".tif", ".tiff"}
+    image_files = sorted(
+        f for f in stimulus_dir.rglob("*")
+        if f.is_file() and f.suffix.lower() in image_extensions
+    )
+
+    for img in image_files:
+        entry = {
+            "stimulus_file": img.name,
+            "stimulus_path": str(img.relative_to(stimulus_dir)),
+            "category": _extract_category(img),
+        }
+        metadata.append(entry)
+
+    # Look for event files if events_dir provided
+    if events_dir and events_dir.exists():
+        event_files = sorted(events_dir.rglob("*events.tsv"))
+        for ef in event_files:
+            try:
+                with open(ef, "r", encoding="utf-8") as f:
+                    reader = csv.DictReader(f, delimiter="\t")
+                    for row in reader:
+                        if "stim_file" in row or "stimulus_file" in row:
+                            stim = row.get("stim_file", row.get("stimulus_file", ""))
+                            for entry in metadata:
+                                if entry["stimulus_file"] == stim:
+                                    entry["onset"] = row.get("onset", "")
+                                    entry["duration"] = row.get("duration", "")
+                                    entry["trial_type"] = row.get("trial_type", "")
+                                    break
+            except Exception:
+                pass
+
+    return metadata
+
+
+def _extract_category(image_path: Path) -> str:
+    """Try to extract category from image filename or parent directory."""
+    # BOLD5000 uses COCO categories in filenames
+    name = image_path.stem.lower()
+    parent = image_path.parent.name.lower()
+
+    # Common COCO/scene categories
+    categories = [
+        "person", "bicycle", "car", "motorcycle", "airplane", "bus", "train",
+        "truck", "boat", "traffic", "fire", "stop", "parking", "bench", "bird",
+        "cat", "dog", "horse", "sheep", "cow", "elephant", "bear", "zebra",
+        "giraffe", "backpack", "umbrella", "handbag", "tie", "suitcase", "frisbee",
+        "skis", "snowboard", "sports", "kite", "baseball", "skateboard", "surfboard",
+        "tennis", "bottle", "wine", "cup", "fork", "knife", "spoon", "bowl",
+        "banana", "apple", "sandwich", "orange", "broccoli", "carrot", "hot",
+        "pizza", "donut", "cake", "chair", "couch", "potted", "bed", "dining",
+        "toilet", "tv", "laptop", "mouse", "remote", "keyboard", "cell",
+        "microwave", "oven", "toaster", "sink", "refrigerator", "book", "clock",
+        "vase", "scissors", "teddy", "hair", "toothbrush", "indoor", "outdoor",
+        "scene", "building", "mountain", "forest", "ocean", "beach", "desert",
+    ]
+
+    for cat in categories:
+        if cat in name or cat in parent:
+            return cat
+
+    return "unknown"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Extract BOLD5000 stimulus metadata.")
+    parser.add_argument("--stimulus-dir", required=True, help="Path to BOLD5000 stimuli directory")
+    parser.add_argument("--events-dir", help="Path to BOLD5000 events directory")
+    parser.add_argument("--output", required=True, help="Output path for stimulus metadata CSV")
+    args = parser.parse_args()
+
+    stimulus_dir = Path(args.stimulus_dir).resolve()
+    events_dir = Path(args.events_dir).resolve() if args.events_dir else None
+
+    if not stimulus_dir.exists():
+        print(f"Stimulus directory not found: {stimulus_dir}", file=sys.stderr)
+        return 1
+
+    print(f"Extracting stimulus metadata from {stimulus_dir}...")
+    metadata = extract_stimulus_metadata(stimulus_dir, events_dir)
+
+    if not metadata:
+        print("[WARN] No stimulus files found.")
+        return 1
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(output_path, "w", encoding="utf-8", newline="") as f:
+        writer = csv.DictWriter(f, fieldnames=metadata[0].keys(), delimiter="\t")
+        writer.writeheader()
+        writer.writerows(metadata)
+
+    print(f"Wrote {len(metadata)} stimulus entries to {output_path}")
+
+    # Print category summary
+    categories = {}
+    for entry in metadata:
+        cat = entry.get("category", "unknown")
+        categories[cat] = categories.get(cat, 0) + 1
+    print(f"\nCategory distribution ({len(categories)} categories):")
+    for cat, count in sorted(categories.items(), key=lambda x: -x[1])[:15]:
+        print(f"  {cat}: {count}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/bold5000-skill/scripts/reorganize_bold5000.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Verify and reorganize BOLD5000 data into BIDS-compliant layout.
+
+BOLD5000 from OpenNeuro is already in BIDS format; this script validates
+and optionally copies/reorganizes the structure.
+"""
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def validate_bids_structure(root: Path) -> list:
+    """Validate BIDS structure and return list of issues."""
+    issues = []
+    desc = root / "dataset_description.json"
+    if not desc.exists():
+        issues.append("Missing dataset_description.json")
+    else:
+        try:
+            data = json.loads(desc.read_text(encoding="utf-8"))
+            if "BIDSVersion" not in data:
+                issues.append("dataset_description.json missing BIDSVersion")
+        except Exception:
+            issues.append("dataset_description.json is not valid JSON")
+
+    participants = root / "participants.tsv"
+    if not participants.exists():
+        issues.append("Missing participants.tsv")
+
+    subject_dirs = sorted(root.glob("sub-*"))
+    if not subject_dirs:
+        issues.append("No subject directories found (sub-*)")
+    else:
+        for sub_dir in subject_dirs:
+            if not sub_dir.is_dir():
+                continue
+            anat = sub_dir / "anat"
+            func = sub_dir / "func"
+            if not anat.exists() and not func.exists():
+                # Check for session directories
+                ses_dirs = list(sub_dir.glob("ses-*"))
+                if not ses_dirs:
+                    issues.append(f"{sub_dir.name}: no anat/, func/, or ses-* directories")
+                else:
+                    for ses in ses_dirs:
+                        if not (ses / "anat").exists() and not (ses / "func").exists():
+                            issues.append(f"{sub_dir.name}/{ses.name}: no anat/ or func/ directories")
+
+    return issues
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Verify and reorganize BOLD5000 BIDS data.")
+    parser.add_argument("--input", required=True, help="Path to BOLD5000 data directory")
+    parser.add_argument("--output", help="Path to output BIDS directory (if copy needed)")
+    parser.add_argument("--validate-only", action="store_true", help="Only validate, do not copy")
+    parser.add_argument("--dry-run", action="store_true", help="Preview without copying")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    if not input_dir.exists():
+        print(f"Input directory does not exist: {input_dir}", file=sys.stderr)
+        return 1
+
+    print(f"Validating BIDS structure at {input_dir}...")
+    issues = validate_bids_structure(input_dir)
+
+    if issues:
+        print(f"\nFound {len(issues)} issue(s):")
+        for issue in issues:
+            print(f"  - {issue}")
+    else:
+        print("BIDS structure is valid.")
+
+    if args.validate_only:
+        return 1 if issues else 0
+
+    output_dir = Path(args.output).resolve() if args.output else None
+    if output_dir:
+        print(f"\n{'[DRY RUN] ' if args.dry_run else ''}Copying to {output_dir}...")
+        if not args.dry_run:
+            output_dir.mkdir(parents=True, exist_ok=True)
+            # Copy BIDS structure
+            for item in input_dir.iterdir():
+                dst = output_dir / item.name
+                if item.is_dir():
+                    if not dst.exists():
+                        shutil.copytree(str(item), str(dst))
+                else:
+                    if not dst.exists():
+                        shutil.copy2(str(item), str(dst))
+            print("Copy complete.")
+        else:
+            print("[DRY RUN] Would copy all BIDS files to output directory.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,213 @@
+---
+name: camcan-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the Cam-CAN (Cambridge Centre for Ageing and Neuroscience) dataset, including BIDS validation, multimodal processing of sMRI, rs-fMRI, task-fMRI, and MEG, phenotype extraction, and QC integration. Triggers include: 'Cam-CAN', 'CamCAN', 'process Cam-CAN data', 'Cam-CAN MEG', 'Cam-CAN fMRI', or any request to run the Cam-CAN multimodal pipeline."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - fmri-skill
+  - meg-skill
+  - bids-organizer
+  - claw-shell
+complementary_skills:
+  - mne-eeg-tool
+---
+# Cam-CAN Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`camcan-skill` is the NeuroClaw orchestration skill for the **Cam-CAN (Cambridge Centre for Ageing and Neuroscience)** 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 BIDS validation, phenotype extraction, and QC.
+
+**Core workflow (never bypassed):**
+1. Identify input Cam-CAN 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 (`camcan_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| BIDS validation | Validate Cam-CAN BIDS structure | `scripts/validate_camcan.py` | Validation report |
+| sMRI processing | Brain extraction, tissue segmentation, cortical reconstruction | `smri-skill` | `smri_output/` derivatives |
+| rs-fMRI processing | Preprocessing, denoising, connectivity | `fmri-skill` | `fmri_output/` derivatives |
+| task-fMRI processing | Movie-watching task GLM, activation analysis | `fmri-skill` | `fmri_output/` task results |
+| MEG processing | Source localization, time-frequency analysis | `meg-skill` | `meg_output/` TFR and source |
+| Phenotype extraction | Cognitive, sensory, health measures | `scripts/extract_camcan_phenotype.py` | Merged phenotype CSV |
+| QC summary | Per-subject quality control | `scripts/camcan_qc_summary.py` | QC summary + exclusion list |
+
+---
+
+## Dataset Characteristics
+
+- **Cohort**: ~700 participants spanning the adult lifespan (18-88 years)
+- **Design**: Cross-sectional population-based sample
+- **Site**: MRC Cognition and Brain Sciences Unit, Cambridge, UK
+- **Scanner**: Siemens 3T TIM TRIO
+- **MEG system**: CTF 275-channel system
+- **Access**: OpenNeuro ds003097 (CC0 license)
+
+---
+
+## Supported Modalities
+
+| Modality | Description | Tasks/Conditions |
+|---|---|---|
+| T1w | High-resolution structural MRI | Single acquisition |
+| T2*w | Functional MRI (multi-echo EPI) | Resting-state (eyes open), Movie-watching |
+| MEG | Magnetoencephalography | Resting-state (eyes open), Auditory (passive listening), Visual (passive viewing) |
+| dMRI | Diffusion-weighted imaging | DTI tractography |
+
+---
+
+## Cam-CAN Task Paradigms
+
+### fMRI Tasks
+| Task | Description | Duration |
+|---|---|---|
+| REST | Resting-state (eyes open) | ~8 min |
+| MOVIE | Movie-watching (feature film excerpts) | ~15 min |
+
+### MEG Tasks
+| Task | Description | Duration |
+|---|---|---|
+| REST | Resting-state (eyes open, eyes closed) | ~8 min |
+| AUDITORY | Passive listening to tones and speech | ~5 min |
+| VISUAL | Passive viewing of visual stimuli | ~5 min |
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/validate_camcan.py`
+
+Validates Cam-CAN BIDS structure and generates a compliance report.
+
+```bash
+python skills/camcan-skill/scripts/validate_camcan.py \
+  --input /path/to/CamCAN/bids \
+  --output /path/to/camcan_output/qc/bids_validation.csv
+```
+
+Features:
+- BIDS directory structure validation
+- Modality completeness check (T1w, T2*w, MEG, dMRI)
+- Sidecar JSON presence and content validation
+- Participant ID consistency across modalities
+- Missing data identification and reporting
+
+---
+
+## Core Workflow (Never Bypassed)
+
+1. Identify user target: full Cam-CAN processing, imaging subset, phenotype 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_camcan.py`.
+5. Delegate to `smri-skill` for structural MRI processing.
+6. Delegate to `fmri-skill` for functional MRI processing (resting-state and movie-watching).
+7. Delegate to `meg-skill` for MEG processing (source localization, time-frequency analysis).
+8. If phenotype extraction is requested, run `scripts/extract_camcan_phenotype.py`.
+9. If QC summary is requested, run `scripts/camcan_qc_summary.py`.
+10. Save outputs into `camcan_output/`.
+
+---
+
+## Modality Processing Delegation
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w) | `smri-skill` | brain extraction, tissue segmentation, cortical reconstruction | `smri_output/` derivatives |
+| fMRI (T2*w) | `fmri-skill` | preprocessing, denoising, connectivity, task GLM | `fmri_output/` derivatives |
+| MEG | `meg-skill` | source localization, time-frequency, connectivity | `meg_output/` TFR and source |
+| dMRI | `dwi-skill` | diffusion preprocessing, tensor metrics | `dwi_output/` metrics |
+
+---
+
+## Standard Output Layout
+
+```
+camcan_output/
+├── bids/                   # BIDS-staged data (or validation report)
+├── smri/                   # Structural MRI derivatives
+├── fmri/                   # Functional MRI derivatives (rest + movie)
+├── meg/                    # MEG derivatives (TFR, source, connectivity)
+├── dwi/                    # Diffusion MRI derivatives
+├── phenotype/              # Merged phenotype tables
+├── 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 Cam-CAN data validation or staging.
+
+- If the task starts from Cam-CAN data already present on disk and only asks for BIDS validation:
+  - Skip the download stage
+  - Default to the narrow path `local Cam-CAN 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
+- Cam-CAN is a population-based sample spanning the full adult lifespan (18-88 years).
+- MEG data uses CTF 275-channel system; MEG processing requires system-specific handling.
+- Movie-watching fMRI is a unique task paradigm; standard GLM may not apply.
+- Age range is a key variable; consider age-stratified analyses.
+- Data is available on OpenNeuro ds003097 in BIDS format.
+- `camcan-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end Cam-CAN workflow.
+- User asks to process Cam-CAN MRI and/or MEG data.
+- User needs BIDS validation for Cam-CAN data.
+- User asks to extract Cam-CAN phenotype data (cognitive, sensory, health).
+- User asks for age-related brain imaging analysis using Cam-CAN.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill` → structural MRI preprocessing
+- `fmri-skill` → functional MRI preprocessing and analysis
+- `meg-skill` → MEG processing (source localization, time-frequency)
+- `mne-eeg-tool` → MNE-Python EEG/MEG 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
+- Cam-CAN: https://camcan.mrc-cbu.cam.ac.uk/
+- OpenNeuro ds003097: https://openneuro.org/datasets/ds003097
+- Shafto et al. (2014): The Cam-CAN study protocol. BMC Neurology.
+- Taylor et al. (2017): The Cam-CAN data repository. NeuroImage.
+
+Created At: 2026-05-06 13:31 HKT
+Last Updated At: 2026-05-06 13:31 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/camcan-skill/scripts/camcan_qc_summary.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for Cam-CAN processing.
+
+Combines fMRIPrep confounds, FreeSurfer metrics, and MEG QC
+to produce a unified QC summary with exclusion recommendations.
+"""
+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")}
+    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."""
+    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], fd_threshold: float = 0.3) -> List[str]:
+    """Check exclusion criteria."""
+    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 Cam-CAN 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="FD 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.", file=sys.stderr)
+        return 1
+
+    results = []
+    excluded = []
+    for subj in sorted(subjects):
+        metrics = {"subject_id": subj}
+
+        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]))
+
+        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, 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())