@brainpilot/skills 0.0.6 → 0.0.8

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

@@ -0,0 +1,215 @@
+---
+name: hcpep-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the HCP Early Psychosis (HCP-EP) dataset, including dataset download, BIDS organization, and multimodal processing of sMRI, fMRI, and dMRI. Triggers include: 'HCP Early Psychosis', 'HCP-EP', 'process HCP Early Psychosis data', 'HCP EP sMRI fMRI', or any request to run the HCP-EP 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-EP Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`hcpep-skill` is the NeuroClaw orchestration skill for the **HCP Early Psychosis (HCP-EP)** 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-EP 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 (`hcpep_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| Data download | Download HCP-EP from ConnectomeDB | `claw-shell` | Raw HCP-EP files |
+| BIDS staging | Reorganize HCP-EP native layout to BIDS | `scripts/reorganize_hcpep.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 | Clinical, diagnostic, cognitive data | `scripts/extract_hcpep_phenotype.py` | Merged phenotype CSV |
+| QC summary | Per-subject quality control | `scripts/hcpep_qc_summary.py` | QC summary + exclusion list |
+
+---
+
+## Download Stage (Mandatory First Step)
+
+### Source
+HCP-EP data is distributed through **ConnectomeDB**:
+- Website: https://db.humanconnectome.org/
+- Requires ConnectomeDB account and data use agreement
+- Part of the HCP Clinical initiative
+
+### Dataset Characteristics
+- **Cohort**: ~250 participants (early psychosis and healthy controls)
+- **Modalities**: T1w, T2w, dMRI, rs-fMRI, task-fMRI
+- **Focus**: Early psychosis (schizophrenia spectrum, bipolar disorder), neural circuit disruptions
+- **Unique feature**: Clinical cohort with matched healthy controls for case-control comparisons
+
+### Diagnostic Groups
+- Early psychosis patients (schizophrenia spectrum, bipolar with psychotic features)
+- Healthy controls (age-, sex-, and education-matched)
+- All patients are within 5 years of psychosis onset
+
+### Download Inputs to Confirm in Plan
+- ConnectomeDB credentials/token
+- Target modalities (all, structural, functional, diffusion)
+- Subject list scope (full or custom subset)
+- Destination directory with sufficient disk space
+
+---
+
+## HCP-EP 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_hcpep.py`
+
+Converts HCP-EP native directory structure to BIDS-compliant layout.
+
+```bash
+python skills/hcpep-skill/scripts/reorganize_hcpep.py \
+  --input /path/to/HCPEP/raw \
+  --output /path/to/HCPEP/bids \
+  --participants /path/to/subject_list.txt
+```
+
+Features:
+- Subject ID normalization: HCP format to BIDS `sub-` labels
+- Diagnostic group labeling (patient vs. control)
+- Modality routing: T1w, T2w, dMRI, rs-fMRI, task-fMRI
+- 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-EP 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_hcpep.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_hcpep_phenotype.py`.
+10. If QC summary is requested, run `scripts/hcpep_qc_summary.py`.
+11. Save outputs into `hcpep_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
+
+```
+hcpep_output/
+├── raw/                    # Downloaded original HCP-EP files
+├── bids/                   # BIDS-staged data
+├── smri/                   # Structural MRI derivatives
+├── fmri/                   # Functional MRI derivatives
+├── dwi/                    # Diffusion MRI derivatives
+├── phenotype/              # Merged phenotype tables (diagnosis, clinical, cognitive)
+├── qc/                     # QC summaries and exclusion lists
+└── logs/                   # Download + orchestration logs
+```
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full orchestration when the task only asks for local HCP-EP data staging.
+
+- If the task starts from raw HCP-EP 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-EP 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
+- HCP-EP is a clinical cohort; patient data requires careful handling and de-identification.
+- Early psychosis patients may have higher motion artifacts; QC thresholds may need adjustment.
+- Case-control matching should be verified before group comparisons.
+- For HCP-native preprocessing, optionally delegate to `hcppipeline-tool`.
+- `hcpep-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end HCP Early Psychosis workflow.
+- User asks to download HCP-EP and run sMRI/fMRI/DTI processing.
+- User needs BIDS staging for HCP-EP data.
+- User asks to extract HCP-EP phenotype data (diagnosis, clinical, cognitive).
+
+---
+
+## 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 Early Psychosis: https://www.humanconnectome.org/study/hcp-early-psychosis
+- ConnectomeDB: https://db.humanconnectome.org/
+- Heckers et al. (2024): The HCP Early Psychosis project
+
+Created At: 2026-05-06 13:02 HKT
+Last Updated At: 2026-05-06 13:02 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/hcpep-skill/scripts/extract_hcpep_phenotype.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Extract and merge HCP Early Psychosis phenotype data.
+
+Focuses on clinical measures: diagnosis, symptom severity, medication,
+cognitive assessment, and functional outcomes for early psychosis research.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+COLUMN_MAP = {
+    "subject_id": ["Subject", "subject", "PIN"],
+    "age": ["Age_in_Yrs", "Age"],
+    "sex": ["Gender", "Sex"],
+    "handedness": ["Handedness"],
+    "race": ["Race"],
+    "ethnicity": ["Ethnicity"],
+    # Clinical diagnosis
+    "diagnosis": ["Diagnosis", "Group"],
+    "diagnosis_detail": ["Diagnosis_Detail"],
+    "patient_control": ["Patient_Control"],
+    # Symptom measures
+    "panss_positive": ["PANSS_Positive"],
+    "panss_negative": ["PANSS_Negative"],
+    "panss_general": ["PANSS_General"],
+    "panss_total": ["PANSS_Total"],
+    "bprs_total": ["BPRS_Total"],
+    "bprs_positive": ["BPRS_Positive"],
+    "bprs_negative": ["BPRS_Negative"],
+    "gaf_score": ["GAF_Score"],
+    "saps_total": ["SAPS_Total"],
+    "sans_total": ["SANS_Total"],
+    # Medication
+    "medication_status": ["Medication", "Med_Status"],
+    "chlorpromazine_eq": ["CPZ_Equivalent", "Chlorpromazine_Eq"],
+    # Functional measures
+    "functioning_gaf": ["GAF_Functioning"],
+    "role_functioning": ["Role_Functioning"],
+    "social_functioning": ["Social_Functioning"],
+    # Cognitive measures
+    "matrics_overall": ["MCCB_Overall", "MATRICS_Overall"],
+    "matrics_speed": ["MCCB_Speed", "Processing_Speed"],
+    "matrics_attention": ["MCCB_Attention", "Attention_Vigilance"],
+    "matrics_working_mem": ["MCCB_Working_Memory"],
+    "matrics_verbal": ["MCCB_Verbal_Learning"],
+    "matrics_visual": ["MCCB_Visual_Learning"],
+    "matrics_reasoning": ["MCCB_Reasoning"],
+    "matrics_social_cog": ["MCCB_Social_Cognition"],
+    # Duration of illness
+    "duration_illness": ["Duration_Illness", "DUI"],
+    "duration_untreated": ["Duration_Untreated", "DUP"],
+    "age_onset": ["Age_Onset"],
+}
+
+
+def load_csv(path: Path) -> List[Dict[str, str]]:
+    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]:
+    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]]:
+    all_data = []
+    for fpath in phenotype_files:
+        all_data.extend(load_csv(fpath))
+
+    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 HCP Early Psychosis phenotype data.")
+    parser.add_argument("--phenotype-files", required=True, nargs="+")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--imaging-ids")
+    parser.add_argument("--columns")
+    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/hcpep-skill/scripts/hcpep_qc_summary.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for HCP Early Psychosis processing.
+
+Clinical-specific: adjusted thresholds for patient data, diagnostic group tracking.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+
+def load_confounds(confounds_path: Path) -> Dict[str, float]:
+    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]:
+    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. Same threshold for patients and controls."""
+    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 HCP-EP.")
+    parser.add_argument("--fmriprep-dir")
+    parser.add_argument("--freesurfer-dir")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--exclude-output")
+    parser.add_argument("--fd-threshold", type=float, default=0.3)
+    parser.add_argument("--diagnosis-file", help="CSV with subject diagnosis info")
+    args = parser.parse_args()
+
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Load diagnosis info if available
+    diagnosis_map = {}
+    if args.diagnosis_file:
+        diag_path = Path(args.diagnosis_file).resolve()
+        if diag_path.exists():
+            import csv as csv_mod
+            with open(diag_path, "r", encoding="utf-8") as f:
+                reader = csv_mod.DictReader(f)
+                for row in reader:
+                    subj = row.get("subject_id") or row.get("Subject", "")
+                    diag = row.get("diagnosis") or row.get("Diagnosis") or row.get("Group", "")
+                    if subj and diag:
+                        diagnosis_map[subj] = diag
+
+    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}
+
+        # Add diagnosis if available
+        if diagnosis_map:
+            metrics["diagnosis"] = diagnosis_map.get(subj, "unknown")
+
+        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())

package/skills/06_fMRI_Neuroimaging/hcpep-skill/scripts/reorganize_hcpep.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Reorganize HCP Early Psychosis native layout to BIDS structure."""
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+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:
+    return f"sub-{hcp_id.strip()}"
+
+
+def find_subjects(input_dir: Path, participant_list: list = None) -> list:
+    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:
+    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)
+
+    mninonlinear = subject_dir / "MNINonLinear"
+
+    for suffix in ["T1w.nii.gz", "T2w.nii.gz"]:
+        src = mninonlinear / suffix
+        if src.exists():
+            modality = suffix.split(".")[0].lower()
+            dst = sub_dir / "anat" / f"{bids_id}_{modality}.nii.gz"
+            if not dry_run:
+                shutil.copy2(src, dst)
+            report["files_created"] += 1
+        else:
+            report["warnings"].append(f"{suffix} not found")
+
+    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():
+            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:
+                dst_name = f"{bids_id}_task-{task_info['label']}_run-01_bold.nii.gz"
+                dst = sub_dir / "func" / dst_name
+                if not dry_run:
+                    shutil.copy2(bold_src, dst)
+                report["files_created"] += 1
+
+    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):
+    desc = {
+        "Name": "HCP Early Psychosis",
+        "BIDSVersion": "1.8.0",
+        "DatasetType": "raw",
+        "License": "HCP Data Use Terms",
+        "Authors": ["Human Connectome Project"],
+        "HowToAcknowledge": "Please cite the HCP Early Psychosis project.",
+        "ReferencesAndLinks": ["https://www.humanconnectome.org/study/hcp-early-psychosis"],
+        "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-EP native layout to BIDS.")
+    parser.add_argument("--input", required=True)
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--participants")
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    output_dir = Path(args.output).resolve()
+
+    if not input_dir.exists():
+        print(f"Input not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    participant_list = None
+    if args.participants:
+        p_file = Path(args.participants).resolve()
+        if p_file.exists():
+            participant_list = [l.strip() for l in p_file.read_text().splitlines() if l.strip()]
+
+    subjects = find_subjects(input_dir, participant_list)
+    print(f"Found {len(subjects)} subjects")
+
+    if not args.dry_run:
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    total_files = 0
+    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 (i + 1) % 50 == 0 or (i + 1) == len(subjects):
+            print(f"  Processed {i + 1}/{len(subjects)} subjects")
+
+    if not args.dry_run:
+        create_dataset_description(output_dir, len(subjects))
+
+    print(f"\nBIDS Staging: {len(subjects)} subjects, {total_files} files -> {output_dir}")
+    if args.dry_run:
+        print("  [DRY RUN]")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())