@brainpilot/skills 0.0.6 → 0.0.8

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

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Extract and merge Cam-CAN phenotype data.
+
+Reads Cam-CAN phenotype files (cognitive, sensory, health measures)
+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 mapping for Cam-CAN phenotype data
+COLUMN_MAP = {
+    "subject_id": ["subject", "Subject", "participant_id", "SubID"],
+    "age": ["age", "Age", "Age_in_Yrs"],
+    "sex": ["sex", "Sex", "Gender"],
+    "handedness": ["handedness", "Handedness"],
+    # Cognitive measures
+    "picture_vocab": ["PictureVocab", "picture_vocab_score"],
+    "card_sorting": ["CardSort", "card_sorting_score"],
+    "flanker": ["Flanker", "flanker_score"],
+    "list_sorting": ["ListSort", "list_sorting_score"],
+    "pattern_comparison": ["PatternComp", "pattern_comparison_score"],
+    "picture_sequence": ["PictureSeq", "picture_sequence_score"],
+    "reading": ["Reading", "reading_score"],
+    # Sensory measures
+    "hearing": ["Hearing", "hearing_threshold"],
+    "vision": ["Vision", "vision_acuity"],
+    # Health measures
+    "mmse": ["MMSE", "mmse_score"],
+    "moca": ["MOCA", "moca_score"],
+    # Grip strength
+    "grip_strength_left": ["GripLeft", "grip_strength_left"],
+    "grip_strength_right": ["GripRight", "grip_strength_right"],
+}
+
+
+def load_csv(path: Path) -> List[Dict[str, str]]:
+    """Load CSV/TSV file and return list of dicts."""
+    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]:
+    """Find the first matching column name in a row."""
+    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]]:
+    """Extract and merge phenotype data from multiple files."""
+    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 Cam-CAN phenotype data."
+    )
+    parser.add_argument("--phenotype-files", required=True, nargs="+",
+                        help="Paths to Cam-CAN phenotype CSV/TSV files")
+    parser.add_argument("--output", required=True, help="Output path for merged phenotype CSV")
+    parser.add_argument("--imaging-ids", help="Text file with imaging subject IDs to filter")
+    parser.add_argument("--columns", help="Comma-separated columns to extract")
+    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/camcan-skill/scripts/validate_camcan.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Validate Cam-CAN BIDS structure and generate compliance report.
+
+Checks directory structure, modality completeness, sidecar JSON presence,
+and participant ID consistency across modalities.
+"""
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+# Expected modalities for Cam-CAN
+EXPECTED_MODALITIES = {
+    "anat": ["T1w"],
+    "func": ["task-rest_bold", "task-movie_bold"],
+    "meg": ["task-rest_meg", "task-auditory_meg", "task-visual_meg"],
+    "dwi": ["dwi"],
+}
+
+
+def validate_subject(subject_dir: Path) -> Dict[str, any]:
+    """Validate a single subject's BIDS structure."""
+    report = {
+        "subject": subject_dir.name,
+        "anat_complete": False,
+        "func_complete": False,
+        "meg_complete": False,
+        "dwi_complete": 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")
+        # Check sidecar JSON
+        for f in t1w_files:
+            json_file = f.with_suffix("").with_suffix(".json")
+            if not json_file.exists():
+                report["warnings"].append(f"Missing sidecar: {json_file.name}")
+    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"))
+        movie_bold = list(func_dir.glob("*_task-movie_bold.nii.gz"))
+        report["func_complete"] = len(rest_bold) > 0 and len(movie_bold) > 0
+        if not rest_bold:
+            report["missing_files"].append("func/*_task-rest_bold.nii.gz")
+        if not movie_bold:
+            report["missing_files"].append("func/*_task-movie_bold.nii.gz")
+    else:
+        report["missing_files"].append("func/")
+
+    # Check meg
+    meg_dir = subject_dir / "meg"
+    if meg_dir.exists():
+        meg_files = list(meg_dir.glob("*_meg.fif"))
+        if not meg_files:
+            meg_files = list(meg_dir.glob("*_meg.ds"))
+        report["meg_complete"] = len(meg_files) > 0
+        if not meg_files:
+            report["missing_files"].append("meg/*_meg.fif or .ds")
+    else:
+        report["missing_files"].append("meg/")
+
+    # Check dwi
+    dwi_dir = subject_dir / "dwi"
+    if dwi_dir.exists():
+        dwi_files = list(dwi_dir.glob("*_dwi.nii.gz"))
+        report["dwi_complete"] = len(dwi_files) > 0
+        if not dwi_files:
+            report["missing_files"].append("dwi/*_dwi.nii.gz")
+    else:
+        report["missing_files"].append("dwi/")
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate Cam-CAN BIDS structure."
+    )
+    parser.add_argument("--input", required=True, help="Path to Cam-CAN 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", "meg_complete", "dwi_complete", "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 MEG: {sum(1 for r in results if r['meg_complete'])}")
+    print(f"  With DWI: {sum(1 for r in results if r['dwi_complete'])}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,201 @@
+---
+name: cobre-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the COBRE dataset, including download, BIDS organization, and processing of sMRI and rs-fMRI data for schizophrenia research. Triggers include: 'COBRE', 'process COBRE', 'COBRE schizophrenia', 'COBRE fMRI', or any request to run the COBRE pipeline. This is the NeuroClaw dataset-orchestration layer for COBRE."
+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
+---
+# COBRE Skill (Dataset-Orchestration Layer)
+
+## Overview
+`cobre-skill` is the NeuroClaw orchestration skill for the **COBRE (Center for Biomedical Research Excellence)** dataset.
+
+COBRE contains 147 participants: 72 schizophrenia patients and 75 healthy controls, with T1w structural and rs-fMRI data. It is commonly used as a benchmark for brain disorder classification.
+
+It coordinates a fixed three-phase workflow:
+1. Download COBRE data from the FCP/INDI repository.
+2. Prepare and validate BIDS-style data organization for downstream processing.
+3. Delegate modality pipelines to `smri-skill` and `fmri-skill`.
+
+It also provides **phenotype extraction** and **QC integration** paths:
+- Extract COBRE phenotype data (diagnosis, demographics, handedness).
+- Generate per-subject QC summaries with exclusion lists.
+
+This skill follows NeuroClaw hierarchy:
+- Defines **WHAT to do**, not low-level implementation details.
+- Does **not** execute direct shell commands itself.
+- Delegates all execution via `claw-shell` to base/tool skills.
+
+**Research use only.**
+
+---
+
+## Download Stage (Mandatory First Step)
+
+### Source
+COBRE data is distributed through the **FCP/INDI** repository:
+- Website: https://fcon_1000.projects.nitrc.org/indi/retro/cobre.html
+
+### Supported COBRE Data Packages
+- **Imaging data**: T1w, rs-fMRI (NIfTI format)
+- **Phenotype data**: CSV files with diagnosis, demographics, handedness
+- **Participants**: 147 total (72 schizophrenia, 75 healthy controls)
+
+### Delegation Rules for Download
+- Environment/setup checks: `dependency-planner` + `conda-env-manager`
+- Download tool installation and execution: `claw-shell`
+- Optional raw-data organization to BIDS-style staging: `bids-organizer`
+
+### Download Inputs to Confirm in Plan
+- Subject list scope (full or custom subset)
+- Whether to download raw data or preprocessed derivatives
+- Destination directory with sufficient disk space
+
+---
+
+## Narrow Path: COBRE Raw NIfTI -> BIDS Staging
+
+Use this path when the task only asks to reorganize raw COBRE NIfTI files into a BIDS-style dataset and does not require preprocessing or downstream analysis.
+
+### Expected narrow-path behavior
+1. Detect COBRE-style subject IDs (numeric) and normalize to BIDS labels such as `sub-NNNNN`.
+2. Route modalities:
+   - T1w -> `anat/*_T1w`
+   - rs-fMRI/BOLD -> `func/*_task-rest_bold`
+3. Preserve or rename matching JSON sidecars when available.
+4. Emit dataset-level outputs such as `dataset_description.json`, `participants.tsv`.
+
+---
+
+## Core Workflow (Never Bypassed)
+1. Identify user target: full COBRE download, imaging subset, phenotype extraction, 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_cobre.py`.
+6. Delegate to modality skills:
+   - `smri-skill` for structural MRI (T1w)
+   - `fmri-skill` for resting-state fMRI (rs-fMRI)
+7. If phenotype extraction is requested, run `scripts/extract_cobre_phenotype.py`.
+8. If QC summary is requested, run `scripts/cobre_qc_summary.py`.
+9. Save outputs into a COBRE-centered structure under `cobre_output/`.
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/reorganize_cobre.py`
+
+Converts COBRE raw directory structure to BIDS-compliant layout.
+
+```bash
+python skills/cobre-skill/scripts/reorganize_cobre.py \
+  --input /path/to/cobre_raw \
+  --output /path/to/cobre_bids \
+  --phenotype /path/to/cobre_raw/phenotype/cobre_phenotypic.csv
+```
+
+---
+
+## Phenotype Extraction
+
+### Script: `scripts/extract_cobre_phenotype.py`
+
+```bash
+python skills/cobre-skill/scripts/extract_cobre_phenotype.py \
+  --phenotype-dir /path/to/cobre_raw/phenotype \
+  --output /path/to/cobre_output/phenotype/merged_phenotype.csv \
+  --imaging-ids /path/to/cobre_output/bids/participants.tsv
+```
+
+---
+
+## QC Integration
+
+### Script: `scripts/cobre_qc_summary.py`
+
+```bash
+python skills/cobre-skill/scripts/cobre_qc_summary.py \
+  --fmriprep-dir /path/to/cobre_output/fmriprep \
+  --output /path/to/cobre_output/qc/qc_summary.csv \
+  --exclude-output /path/to/cobre_output/qc/exclude_list.csv \
+  --fd-threshold 0.3
+```
+
+---
+
+## Recommended Output Layout
+All assets should be organized under `./cobre_output/`:
+- `cobre_output/raw/` (downloaded original COBRE files)
+- `cobre_output/bids/` (staged BIDS data)
+- `cobre_output/smri/` (links or copies from `smri_output/`)
+- `cobre_output/fmri/` (links or copies from `fmri_output/`)
+- `cobre_output/phenotype/` (merged phenotype tables)
+- `cobre_output/qc/` (QC summaries and exclusion lists)
+- `cobre_output/logs/` (download + orchestration logs)
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full `download -> staging -> multimodal processing` orchestration when the task is only asking for local COBRE data staging or organization.
+
+- If the task starts from raw COBRE data already present on disk and only asks for BIDS-style staging / organization:
+  - skip the mandatory download stage
+  - default to the narrow path `local raw COBRE 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
+- COBRE is a single-site dataset from the University of New Mexico; no site effects to address.
+- COBRE has a small sample size (147 subjects); cross-validation strategies should account for this.
+- Diagnosis labels: schizophrenia (1) vs. healthy control (2).
+- COBRE data does not include task-fMRI; only resting-state fMRI is available.
+- `cobre-skill` is orchestration-only; detailed preprocessing logic remains in `smri-skill` and `fmri-skill`.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end COBRE workflow.
+- User asks to download COBRE data and then run sMRI/rs-fMRI processing.
+- User needs BIDS staging for raw COBRE NIfTI files.
+- User asks to extract COBRE phenotype data.
+- User needs COBRE-specific QC summaries and exclusion lists.
+- User wants to run schizophrenia classification with BrainGNN or other models on COBRE.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill`
+- `fmri-skill`
+- `bids-organizer`
+- `fmriprep-tool`
+- `freesurfer-tool`
+- `brain_gnn`
+- `neurostorm`
+- `dependency-planner`
+- `conda-env-manager`
+- `claw-shell`
+
+---
+
+## Reference
+- COBRE: https://fcon_1000.projects.nitrc.org/indi/retro/cobre.html
+- BIDS spec: https://bids.neuroimaging.io/
+
+Created At: 2026-05-06 01:54 HKT
+Last Updated At: 2026-05-06 01:54 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/cobre-skill/scripts/cobre_qc_summary.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries and exclusion lists for COBRE."""
+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"])
+                else:
+                    qc[subject_id] = metrics
+    return qc
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate COBRE 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/cobre-skill/scripts/extract_cobre_phenotype.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Extract and merge COBRE phenotype tables for downstream analysis."""
+import argparse
+import csv
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+try:
+    import pandas as pd
+except ImportError:
+    print("Error: pandas is required.", file=sys.stderr)
+    sys.exit(1)
+
+COLUMN_MAP = {
+    "subject": "subject_id",
+    "SUBJECT_ID": "subject_id",
+    "Subject": "subject_id",
+    "DX": "diagnosis",
+    "DX_GROUP": "diagnosis",
+    "AGE": "age",
+    "SEX": "sex",
+    "HANDEDNESS": "handedness",
+}
+
+
+def normalize_subject_id(raw_id) -> str:
+    clean = re.sub(r"[^a-zA-Z0-9]", "", str(raw_id).strip())
+    return f"sub-{clean}"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Extract COBRE phenotype data.")
+    parser.add_argument("--phenotype-dir", help="Directory containing COBRE phenotype CSV files")
+    parser.add_argument("--phenotype-file", help="Direct path to COBRE phenotype CSV file")
+    parser.add_argument("--output", required=True, help="Output path for phenotype CSV")
+    parser.add_argument("--imaging-ids", help="Path to BIDS participants.tsv for filtering")
+    args = parser.parse_args()
+
+    phenotype_files = []
+    if args.phenotype_file:
+        p = Path(args.phenotype_file).resolve()
+        if p.exists():
+            phenotype_files.append(p)
+    elif args.phenotype_dir:
+        phenotype_dir = Path(args.phenotype_dir).resolve()
+        if phenotype_dir.exists():
+            phenotype_files = sorted(f for f in phenotype_dir.iterdir() if f.is_file() and f.suffix in (".csv", ".tsv"))
+
+    if not phenotype_files:
+        print("[ERROR] No phenotype files found.", file=sys.stderr)
+        return 1
+
+    print(f"Found {len(phenotype_files)} phenotype file(s)")
+
+    dataframes = []
+    for f in phenotype_files:
+        try:
+            df = pd.read_csv(f, sep=None, engine="python", low_memory=False)
+            rename = {k: v for k, v in COLUMN_MAP.items() if k in df.columns and v not in df.columns}
+            df = df.rename(columns=rename)
+            dataframes.append(df)
+        except Exception as e:
+            print(f"[WARN] Failed to read {f}: {e}")
+
+    if not dataframes:
+        print("[ERROR] No data loaded.", file=sys.stderr)
+        return 1
+
+    merged = dataframes[0]
+    for df in dataframes[1:]:
+        if "subject_id" in merged.columns and "subject_id" in df.columns:
+            new_cols = [c for c in df.columns if c not in merged.columns or c == "subject_id"]
+            merged = pd.merge(merged, df[new_cols], on="subject_id", how="outer")
+        else:
+            merged = pd.concat([merged, df], ignore_index=True)
+
+    if args.imaging_ids:
+        imaging_path = Path(args.imaging_ids).resolve()
+        if imaging_path.exists() and "subject_id" in merged.columns:
+            id_df = pd.read_csv(imaging_path, sep="\t")
+            for col in ["participant_id", "subject_id"]:
+                if col in id_df.columns:
+                    imaging_ids = set(id_df[col].astype(str).str.strip())
+                    normalized = {normalize_subject_id(sid) for sid in imaging_ids} | imaging_ids
+                    merged["_norm"] = merged["subject_id"].apply(normalize_subject_id)
+                    merged = merged[merged["_norm"].isin(normalized) | merged["subject_id"].astype(str).isin(normalized)]
+                    merged = merged.drop(columns=["_norm"])
+                    break
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    merged.to_csv(output_path, index=False)
+    print(f"\nWrote {len(merged)} rows x {len(merged.columns)} columns to {output_path}")
+
+    if "diagnosis" in merged.columns:
+        print(f"\nDiagnosis distribution:\n{merged['diagnosis'].value_counts().to_string()}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())