@brainpilot/skills 0.0.6 → 0.0.8

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

@@ -0,0 +1,217 @@
+---
+name: hcppipeline-tool
+description: "Use this skill whenever the user wants to perform high-quality, HCP-style preprocessing of multimodal MRI data (structural, functional, diffusion) using the official HCP Pipelines. Triggers include: 'HCP pipeline', 'HCP preprocessing', 'hcp-fmri', 'hcp-dwi', 'hcp-structural', 'MSMAll', 'ICA-FIX', 'bedpostx', 'probtrackx', or any request to run the Human Connectome Project preprocessing pipelines."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: base
+skill_type: tool
+dependencies:
+  - claw-shell
+---
+# HCP Pipeline Tool
+
+## Overview
+The HCP Pipelines are the official, highly optimized preprocessing pipelines developed by the Human Connectome Project. They provide state-of-the-art processing for structural (T1w/T2w), functional (task/resting-state fMRI with ICA-FIX), and diffusion MRI (topup + eddy + bedpostx + probtrackx + MSMAll surface alignment).
+
+This skill serves as the **NeuroClaw interface-layer wrapper** for the HCP Pipelines and strictly follows the hierarchical design:
+
+1. Check whether HCP Pipelines and dependencies are installed.
+2. If missing → invoke `dependency-planner` to generate a safe installation plan.
+3. Detect input data (preferably BIDS or HCP-style organized) and confirm processing stages.
+4. Generate a clear, numbered execution plan with exact commands, flags, estimated runtime, and risks.
+5. Present the plan and wait for explicit user confirmation (“YES” / “execute” / “proceed”).
+6. On confirmation → delegate all pipeline stages to `claw-shell`.
+7. After completion, summarize outputs and suggest next steps (e.g., connectivity analysis via `fmri-skill` or `fsl-tool`).
+
+**Research use only.**
+
+## Quick Reference
+
+| Task                              | Recommended Pipeline Stage                          | Typical Runtime (per subject) |
+|-----------------------------------|-----------------------------------------------------|-------------------------------|
+| Structural preprocessing          | PreFreeSurfer + FreeSurfer + PostFreeSurfer         | 4–12 hours                    |
+| Functional preprocessing          | fMRIVolume + fMRISurface + ICA-FIX                  | 2–6 hours                     |
+| Diffusion preprocessing           | DiffusionPreprocessing + bedpostx + probtrackx      | 6–24 hours                    |
+| Surface-based registration        | MSMAll                                              | 2–4 hours                     |
+| Full HCP-style multimodal pipeline| All stages combined                                 | 12–36+ hours                  |
+
+## Common Shell Command Examples
+
+```bash
+# Structural pipeline (benchmark-safe baseline: BIDS-aware discovery + validation first)
+SUBJECT="sub-001"
+SESSION=""
+BIDS_DIR="/data/bids"
+OUTDIR="/data/hcp_output"
+
+if [[ -n "${SESSION}" ]]; then
+    ANAT_DIR="${BIDS_DIR}/${SUBJECT}/${SESSION}/anat"
+    HCP_SUBJECT="${SUBJECT}_${SESSION}"
+else
+    ANAT_DIR="${BIDS_DIR}/${SUBJECT}/anat"
+    HCP_SUBJECT="${SUBJECT}"
+fi
+
+T1W="$(find "${ANAT_DIR}" -maxdepth 1 -type f -name '*_T1w.nii.gz' | sort | head -n 1)"
+T2W="$(find "${ANAT_DIR}" -maxdepth 1 -type f -name '*_T2w.nii.gz' | sort | head -n 1)"
+
+[[ -f "${T1W}" ]] || { echo "Missing required input: T1w"; exit 1; }
+[[ -f "${T2W}" ]] || { echo "Missing required input: T2w"; exit 1; }
+[[ -x "${HCPPIPEDIR}/PreFreeSurfer/PreFreeSurferPipeline.sh" ]] || { echo "Missing required HCP resource: PreFreeSurferPipeline.sh"; exit 1; }
+
+${HCPPIPEDIR}/PreFreeSurfer/PreFreeSurferPipeline.sh \
+    --path="${OUTDIR}" \
+    --subject="${HCP_SUBJECT}" \
+    --t1="${T1W}" \
+    --t2="${T2W}" \
+    --SEPhaseNeg=NONE \
+    --SEPhasePos=NONE \
+    --gdcoeffs=NONE
+
+# Functional pipeline with ICA-FIX
+${HCPPIPEDIR}/fMRIVolume/fMRIVolumePipeline.sh \
+  --path=/data/hcp_output \
+  --subject=sub-001 \
+  --fmriname=rfMRI_REST1 \
+  --fmritcs=/data/bids/sub-001/func/sub-001_task-rest_bold.nii.gz
+
+# Diffusion pipeline
+${HCPPIPEDIR}/DiffusionPreprocessing/DiffusionPreprocessing.sh \
+  --path=/data/hcp_output \
+  --subject=sub-001
+```
+
+## Installation (Handled by dependency-planner)
+Use `dependency-planner` with one of the following requests:
+- “Install official HCP Pipelines from GitHub”
+- “Install HCP Pipelines and dependencies (FSL, FreeSurfer, CUDA if needed)”
+
+After installation, verify with:
+```bash
+echo $HCPPIPEDIR
+```
+
+**Prerequisites**:
+- FSL, FreeSurfer (with valid license)
+- MATLAB (for some legacy parts) or Octave
+- Sufficient disk space (20–100 GB per subject) and RAM (≥32 GB recommended)
+
+## NeuroClaw recommended wrapper script
+Use this only as a last-resort orchestration reference. For benchmark-style tasks, prefer a direct task-level shell plan that first discovers BIDS inputs, checks required HCP resources, and only then calls the official stage script.
+
+```python
+# hcppipeline_wrapper.py (placed inside the skill folder for reference)
+import subprocess
+import argparse
+
+def run_hcp_stage(stage, subject, bids_dir, output_dir):
+    env = {"HCPPIPEDIR": "/opt/HCP-Pipelines"}
+    cmd = [
+        f"{env['HCPPIPEDIR']}/{stage}/{stage}Pipeline.sh",
+        "--path", output_dir,
+        "--subject", subject
+    ]
+    print("Running HCP stage:", stage)
+    subprocess.run(cmd, env=env, check=True)
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--stage", required=True, help="PreFreeSurfer, fMRIVolume, DiffusionPreprocessing, etc.")
+    parser.add_argument("--subject", required=True)
+    parser.add_argument("--bids-dir", required=True)
+    parser.add_argument("--output-dir", required=True)
+    args = parser.parse_args()
+    
+    run_hcp_stage(args.stage, args.subject, args.bids_dir, args.output_dir)
+```
+
+## Important Notes & Limitations
+- All actual pipeline execution is routed through `claw-shell` due to extremely long runtimes.
+- HCP Pipelines are very resource-intensive and disk-heavy.
+- Requires well-organized input data (preferably BIDS via `bids-organizer` first).
+- For benchmark or contract-sensitive tasks, do not stop at the bare `PreFreeSurferPipeline.sh --path --subject --t1 --t2` surface. First resolve BIDS subject/session inputs, validate required template/config resources, and make missing-input or no-fieldmap/no-gdc decisions explicit.
+- ICA-FIX denoising is one of the strongest features of HCP functional pipeline.
+- Surface-based MSMAll registration provides superior alignment compared to volume-based methods.
+
+## When to Call This Skill
+- User wants the highest-quality, HCP-style preprocessing for multimodal data.
+- When research requires accurate surface-based alignment, ICA-FIX cleaned resting-state fMRI, or advanced diffusion modeling.
+- After `bids-organizer` when preparing data for connectomics or high-precision analysis.
+
+## Complementary / Related Skills
+- `bids-organizer` → organize raw data into BIDS before running HCP
+- `fmriprep-tool` → lighter and faster alternative to HCP preprocessing
+- `fsl-tool` → post-HCP connectivity and ROI analysis
+- `dependency-planner` → install HCP Pipelines and dependencies
+- `claw-shell` → safe execution of long-running pipelines
+- `multi-search-engine` / `academic-research-hub` → retrieve latest HCP best practices
+
+## Reference
+Official HCP Pipelines integration for NeuroClaw high-precision multimodal preprocessing.  
+Official repository: https://github.com/Washington-University/HCPpipelines
+
+## Post-Execution Verification (Harness Integration)
+
+After HCP Pipeline processing completes, this skill **automatically invokes harness-core's VerificationRunner** to validate output integrity:
+
+**Integrated verification checks**:
+
+```python
+from skills.harness_core import VerificationRunner, AuditLogger
+
+verifier = VerificationRunner(task_type="hcp_preprocessing")
+
+# 1. Structural preprocessing completion (PreFreeSurfer/FreeSurfer/PostFreeSurfer)
+verifier.add_check("structural_pipeline",
+    checker=lambda: verify_structural_outputs(output_dir),
+    severity="error"
+)
+
+# 2. Functional preprocessing (fMRIVolume/fMRISurface completion)
+verifier.add_check("functional_pipeline",
+    checker=lambda: verify_functional_outputs(output_dir),
+    severity="error"
+)
+
+# 3. Diffusion preprocessing (topup/eddy/bedpostx completion)
+verifier.add_check("diffusion_pipeline",
+    checker=lambda: verify_diffusion_outputs(output_dir),
+    severity="error"
+)
+
+# 4. Surface registration quality (MSMAll)
+verifier.add_check("surface_registration",
+    checker=lambda: verify_surface_registration_quality(output_dir),
+    severity="warning"
+)
+
+# 5. ICA-FIX denoising success (if applied)
+verifier.add_check("ica_fix_denoising",
+    checker=lambda: verify_ica_fix_completion(output_dir),
+    severity="warning"
+)
+
+# 6. Output BIDS compliance
+verifier.add_check("bids_compliance",
+    checker=lambda: verify_bids_structure(output_dir),
+    severity="warning"
+)
+
+report = verifier.run(output_dir)
+
+# Log verification results
+logger = AuditLogger(log_file=f"{output_dir}/hcp_verification.jsonl")
+logger.log_validation(
+    task_name="hcp_preprocessing",
+    checks_passed=len([r for r in report.results if r.passed]),
+    total_checks=len(report.results),
+    output_path=output_dir
+)
+```
+
+**Output**: `{output_dir}/hcp_verification.jsonl` (structured audit log with JSONL format)
+
+---
+
+Created At: 2026-03-25 19:30 HKT  
+Last Updated At: 2026-04-05 02:03 HKT  
+Author: chengwang96

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

@@ -0,0 +1,214 @@
+---
+name: hcpya-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the HCP Young Adult (HCP-YA / HCP1200) dataset, including dataset download, BIDS organization, and multimodal processing of sMRI, fMRI, and dMRI. Triggers include: 'HCP Young Adult', 'HCP-YA', 'HCP1200', 'process HCP data', 'HCP sMRI fMRI DTI', or any request to run the HCP-YA multimodal pipeline."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - fmri-skill
+  - dwi-skill
+  - bids-organizer
+  - claw-shell
+complementary_skills:
+  - hcppipeline-tool
+---
+# HCP-YA Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`hcpya-skill` is the NeuroClaw orchestration skill for the **HCP Young Adult (HCP-YA / HCP1200)** 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 HCP-YA 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 (`hcpya_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| Data download | Download HCP-YA from ConnectomeDB via NeuroSTORM scripts | `claw-shell` | Raw HCP-YA files |
+| BIDS staging | Reorganize HCP-YA native layout to BIDS | `scripts/reorganize_hcpya.py` | BIDS-compliant dataset |
+| sMRI processing | Brain extraction, tissue segmentation, cortical reconstruction | `smri-skill` | `smri_output/` derivatives |
+| fMRI processing | Preprocessing, denoising, connectivity, task GLM | `fmri-skill` | `fmri_output/` derivatives |
+| dMRI processing | Eddy correction, tensor metrics, tractography | `dwi-skill` | `dwi_output/` metrics |
+| Phenotype extraction | Cognitive, behavioral, demographic data | `scripts/extract_hcpya_phenotype.py` | Merged phenotype CSV |
+| QC summary | Per-subject quality control | `scripts/hcpya_qc_summary.py` | QC summary + exclusion list |
+
+---
+
+## Download Stage (Mandatory First Step)
+
+### Source
+HCP-YA data is distributed through **ConnectomeDB**:
+- Website: https://db.humanconnectome.org/
+- Requires ConnectomeDB account and data use agreement
+- NeuroSTORM download scripts available at: https://github.com/CUHK-AIM-Group/NeuroSTORM/tree/main/scripts/dataset_download
+
+### Supported Download Entry Scripts
+- `download_HCP_1200_all.py` (all modalities)
+- `download_HCP_1200_rfMRI.py` (resting-state fMRI)
+- `download_HCP_1200_tfMRI.py` (task fMRI)
+- `download_HCP_1200_t1t2.py` (structural T1w/T2w)
+- `all_pid.pkl` (subject list metadata)
+
+### Download Inputs to Confirm in Plan
+- ConnectomeDB credentials/token
+- Target subset (`all`, `rfMRI`, `tfMRI`, `t1t2`)
+- Subject list scope (full 1,200 or custom subset)
+- Destination directory with sufficient disk space (~80 TB for full dataset)
+
+---
+
+## HCP-YA Task Paradigms
+
+| Task | Description | Duration |
+|---|---|---|
+| MOTOR | Finger tapping, toe movement, tongue movement | ~3 min |
+| EMOTION | Faces and shapes matching | ~2 min |
+| GAMBLING | Card guessing with reward/loss | ~3 min |
+| LANGUAGE | Story comprehension and math | ~4 min |
+| RELATIONAL | Relational reasoning matching | ~3 min |
+| SOCIAL | Social cognition (mentalizing) movie clips | ~3 min |
+| WM | Working memory (faces, places, tools, body parts) | ~5 min |
+| REST | Resting-state (eyes open) | ~15 min × 4 runs |
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/reorganize_hcpya.py`
+
+Converts HCP-YA native directory structure to BIDS-compliant layout.
+
+```bash
+python skills/hcpya-skill/scripts/reorganize_hcpya.py \
+  --input /path/to/HCPYA/raw \
+  --output /path/to/HCPYA/bids \
+  --participants /path/to/subject_list.txt
+```
+
+Features:
+- Subject ID normalization: HCP format (`100307`) to BIDS (`sub-100307`)
+- Modality routing: T1w, T2w, dMRI, rs-fMRI, task-fMRI (7 tasks)
+- Sidecar JSON generation from HCP 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 HCP-YA processing, 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_hcpya.py`.
+6. Delegate to `smri-skill` for structural MRI processing.
+7. Delegate to `fmri-skill` for functional MRI processing.
+8. Delegate to `dwi-skill` for diffusion MRI processing.
+9. If phenotype extraction is requested, run `scripts/extract_hcpya_phenotype.py`.
+10. If QC summary is requested, run `scripts/hcpya_qc_summary.py`.
+11. Save outputs into `hcpya_output/`.
+
+---
+
+## Modality Processing Delegation
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w/T2w) | `smri-skill` | brain extraction, tissue segmentation, cortical reconstruction, ROI morphometry | `smri_output/` derivatives |
+| fMRI (rs-fMRI/task-fMRI) | `fmri-skill` | preprocessing, denoising, ROI time series, connectivity, task GLM | `fmri_output/` derivatives |
+| dMRI (DWI) | `dwi-skill` | eddy correction, tensor metrics, tractography, connectome | `dwi_output/` metrics |
+
+---
+
+## Standard Output Layout
+
+```
+hcpya_output/
+├── raw/                    # Downloaded original HCP-YA files
+├── bids/                   # BIDS-staged data
+├── smri/                   # Structural MRI derivatives
+├── fmri/                   # Functional MRI derivatives
+├── dwi/                    # Diffusion MRI derivatives
+├── phenotype/              # Merged phenotype tables
+├── qc/                     # QC summaries and exclusion lists
+└── logs/                   # Download + orchestration logs
+```
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full `download -> staging -> multimodal processing` orchestration when the task only asks for local HCP-YA data staging or organization.
+
+- If the task starts from raw HCP-YA data already present on disk and only asks for BIDS-style staging:
+  - Skip the mandatory download stage
+  - Default to the narrow path `local raw HCP-YA discovery -> BIDS-style staging -> minimal metadata -> validation/report`
+- In benchmark mode, do not require explicit confirmation before presenting the direct staging solution.
+- Only use the full multimodal orchestration when the prompt explicitly asks for download or end-to-end processing.
+
+---
+
+## 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.
+- If download fails for partial subjects, continue batch with clear failure report and retry list.
+
+---
+
+## Important Notes and Limitations
+- HCP-YA processing is resource intensive (CPU, RAM, and storage).
+- Full HCP-YA dataset is ~80 TB; plan storage accordingly.
+- HCP-YA has 1,200 subjects with complete multimodal data.
+- Age range: 22-35 years.
+- For HCP-native preprocessing (minimal preprocessing pipelines), optionally delegate to `hcppipeline-tool`.
+- `hcpya-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end HCP Young Adult workflow.
+- User asks to download HCP1200 and run sMRI/fMRI/DTI processing.
+- User needs BIDS staging for HCP-YA data.
+- User asks to extract HCP-YA phenotype data (cognitive, behavioral, demographic).
+
+---
+
+## Complementary / Related Skills
+- `smri-skill` → structural MRI preprocessing
+- `fmri-skill` → functional MRI preprocessing and analysis
+- `dwi-skill` → diffusion MRI preprocessing and analysis
+- `hcppipeline-tool` → HCP-native minimal preprocessing pipelines
+- `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
+- HCP-YA: https://www.humanconnectome.org/study/hcp-young-adult
+- ConnectomeDB: https://db.humanconnectome.org/
+- NeuroSTORM download scripts: https://github.com/CUHK-AIM-Group/NeuroSTORM/tree/main/scripts/dataset_download
+- Glasser et al. (2013): The Human Connectome Project minimally preprocessed pipelines
+
+Created At: 2026-05-06 13:02 HKT
+Last Updated At: 2026-05-06 13:02 HKT
+Author: chengwang96

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

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Extract and merge HCP Young Adult phenotype data.
+
+Reads HCP-YA phenotype CSV files (cognitive, behavioral, demographic)
+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: target column name -> possible source column names
+COLUMN_MAP = {
+    "subject_id": ["Subject", "subject", "PIN", "PIN_Subject"],
+    "age": ["Age_in_Yrs", "Age"],
+    "sex": ["Gender", "Sex"],
+    "handedness": ["Handedness", "Handed"],
+    "race": ["Race", "Ethnicity"],
+    "ethnicity": ["Ethnicity"],
+    "education": ["SSAGA_Educ", "Education"],
+    "income": ["SSAGA_Income", "Income"],
+    "height": ["Height_In", "Height"],
+    "weight": ["Weight", "BMI"],
+    "bp_systolic": ["BP_Systolic"],
+    "bp_diastolic": ["BP_Diastolic"],
+    # Cognitive measures
+    "pmat24_a_cr": ["PMAT24_A_CR"],  # Raven's progressive matrices
+    "pmat24_a_si": ["PMAT24_A_SI"],
+    "pmat24_a_rtcr": ["PMAT24_A_RTCR"],
+    "cardsort_unadj": ["CardSort_Unadj"],  # Dimensional change card sort
+    "flanker_unadj": ["Flanker_Unadj"],  # Flanker task
+    "list_unadj": ["List_Unadj"],  # List sorting
+    "picvocab_unadj": ["PicVocab_Unadj"],  # Picture vocabulary
+    "procsp_unadj": ["ProcSpeed_Unadj"],  # Processing speed
+    "readeng_unadj": ["ReadEng_Unadj"],  # Reading
+    "picseq_unadj": ["PicSeq_Unadj"],  # Picture sequence memory
+    "strength_unadj": ["Strength_Unadj"],  # Grip strength
+    "endurance_unadj": ["Endurance_Unadj"],  # Endurance
+    "gait_speed_unadj": ["GaitSpeed_Unadj"],  # Gait speed
+    "dexterity_unadj": ["Dexterity_Unadj"],  # Dexterity
+    # Behavioral/psychiatric
+    "nih_total": ["NIH_TLC"],  # NIH Toolbox Total
+    "neuroticism": ["NEOFAC_N"],
+    "extraversion": ["NEOFAC_E"],
+    "openness": ["NEOFAC_O"],
+    "agreeableness": ["NEOFAC_A"],
+    "conscientiousness": ["NEOFAC_C"],
+    "psqi_global": ["PSQI_Score"],  # Sleep quality
+    "bis_bas_bis": ["BIS_BAS_BIS"],
+    "bis_bas_bas_rr": ["BIS_BAS_BAS_RR"],
+    "bis_bas_bas_d": ["BIS_BAS_BAS_D"],
+    "bis_bas_bas_fs": ["BIS_BAS_BAS_FS"],
+}
+
+
+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."""
+    # Load all files
+    all_data = []
+    for fpath in phenotype_files:
+        rows = load_csv(fpath)
+        for row in rows:
+            all_data.append(row)
+
+    if not all_data:
+        return []
+
+    # Determine which columns to extract
+    if columns:
+        target_columns = columns
+    else:
+        target_columns = list(COLUMN_MAP.keys())
+
+    # Extract and merge
+    merged = {}
+    for row in all_data:
+        # Find subject ID
+        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}
+
+        # Extract requested columns
+        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  # Already have a value
+
+            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()
+
+    # Filter to imaging subjects if provided
+    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 and merge HCP Young Adult phenotype data."
+    )
+    parser.add_argument(
+        "--phenotype-files", required=True, nargs="+",
+        help="Paths to HCP 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 column names to extract (default: all)")
+    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"Phenotype file not found: {f}", file=sys.stderr)
+            return 1
+
+    # Load imaging IDs if provided
+    imaging_ids = None
+    if args.imaging_ids:
+        id_file = Path(args.imaging_ids).resolve()
+        if id_file.exists():
+            imaging_ids = [line.strip() for line in id_file.read_text().splitlines() if line.strip()]
+            print(f"Imaging IDs: {len(imaging_ids)} subjects")
+
+    # Parse columns
+    columns = None
+    if args.columns:
+        columns = [c.strip() for c in args.columns.split(",")]
+        print(f"Requested columns: {columns}")
+
+    # Extract phenotype
+    print(f"Extracting phenotype from {len(phenotype_files)} files...")
+    merged = extract_phenotype(phenotype_files, imaging_ids, columns)
+
+    if not merged:
+        print("[ERROR] No phenotype data extracted.", file=sys.stderr)
+        return 1
+
+    # Write output
+    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"\nPhenotype Summary:")
+    print(f"  Subjects: {len(merged)}")
+    print(f"  Columns: {len(fieldnames)}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())