@brainpilot/skills 0.0.6 → 0.0.7

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

@@ -0,0 +1,244 @@
+---
+name: adhd200-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the ADHD-200 dataset, including download, BIDS organization, and processing of sMRI and rs-fMRI data. Triggers include: 'ADHD-200', 'ADHD200', 'process ADHD data', 'ADHD fMRI', or any request to run the ADHD-200 pipeline. This is the NeuroClaw dataset-orchestration layer for ADHD-200."
+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
+---
+# ADHD-200 Skill (Dataset-Orchestration Layer)
+
+## Overview
+`adhd200-skill` is the NeuroClaw orchestration skill for the **ADHD-200** dataset.
+
+It coordinates a fixed three-phase workflow:
+1. Download ADHD-200 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 and merge ADHD-200 phenotype tables (diagnosis, ADHD measures, demographics, medication).
+- 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
+ADHD-200 data is distributed through the **FCP/INDI** repository:
+- Website: https://fcon_1000.projects.nitrc.org/indi/adhd200/
+
+### Supported ADHD-200 Data Packages
+- **Imaging data**: T1w, rs-fMRI (NIfTI format) from 8 imaging sites
+- **Phenotype data**: CSV files with diagnosis, ADHD measures, demographics, medication history, QC measures
+- **Sites**: Peking, Brown, NYU, KKI, NeuroImage, OHSU, Pitt, Washington University
+
+### 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
+- Target subset (full cohort, specific sites, or ADHD/control only)
+- Subject list scope (full or custom IDs)
+- Destination directory with sufficient disk space
+
+---
+
+## Narrow Path: ADHD-200 Raw NIfTI -> BIDS Staging
+
+Use this path when the task only asks to reorganize raw ADHD-200 NIfTI files into a BIDS-style dataset and does not require preprocessing, ROI extraction, phenotype merging, or downstream analysis.
+
+### When this narrow path should dominate
+- The task objective is limited to ADHD-200 NIfTI staging, BIDS renaming, sidecar handling, and dataset-level metadata.
+- Inputs are already local ADHD-200 NIfTI files or ADHD-200-style subject/site folders.
+- The required deliverable is a direct staging script or command sequence, not a plan for fMRIPrep or downstream analysis.
+
+### Narrow-path contract
+- Do not widen the solution to fMRIPrep, ROI extraction, phenotype merging, or downstream analysis unless the task explicitly requires them.
+- Treat this as a direct file-organization problem: scan ADHD-200 subject/site layout, normalize subject labels, map modalities to BIDS names, copy or symlink NIfTI plus matching sidecars, and write dataset-level metadata plus staging logs.
+- If the task is benchmark-style, prefer a single direct end-to-end staging script over a confirmation-first orchestration plan.
+
+### Expected narrow-path behavior
+1. Detect ADHD-200-style subject IDs (numeric, e.g., `0010002`) and normalize to BIDS labels such as `sub-0010002`.
+2. Detect site information and encode in `participants.tsv`.
+3. Route modalities:
+   - T1w -> `anat/*_T1w`
+   - rs-fMRI/BOLD -> `func/*_task-rest_bold`
+4. Preserve or rename matching JSON sidecars when available.
+5. Emit dataset-level outputs such as `dataset_description.json`, `participants.tsv`, `README`, and a manifest or skipped-file report.
+
+---
+
+## Core Workflow (Never Bypassed)
+1. Identify user target: full ADHD-200 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_adhd200.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_adhd200_phenotype.py`.
+8. If QC summary is requested, run `scripts/adhd200_qc_summary.py`.
+9. Save outputs into an ADHD-200-centered structure under `adhd200_output/`.
+
+---
+
+## Input Layout (Example)
+
+Subject `0010002` from site Peking:
+
+```
+adhd200_raw/
+  Peking/
+    0010002/
+      anat/
+        anat.nii.gz
+      func/
+        rest.nii.gz
+  phenotype/
+    ADHD200_..._phenotypic.csv
+```
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/reorganize_adhd200.py`
+
+Converts ADHD-200 raw directory structure to BIDS-compliant layout.
+
+```bash
+python skills/adhd200-skill/scripts/reorganize_adhd200.py \
+  --input /path/to/adhd200_raw \
+  --output /path/to/adhd200_bids \
+  --phenotype /path/to/adhd200_raw/phenotype/ADHD200_phenotypic.csv
+```
+
+Features:
+- Subject ID normalization: numeric ADHD-200 IDs to BIDS `sub-NNNNNNN`
+- Site extraction and encoding in `participants.tsv`
+- Modality routing: T1w, rs-fMRI
+- `dataset_description.json` and `participants.tsv` generation with phenotype metadata
+- Dry-run mode: `--dry-run` to preview without copying
+
+---
+
+## Multimodal Processing Delegation
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w) | `smri-skill` | brain extraction, tissue segmentation, cortical reconstruction | `smri_output/` |
+| rs-fMRI | `fmri-skill` | preprocessing, denoising, ROI time series, connectivity | `fmri_output/` |
+
+---
+
+## Phenotype Extraction
+
+### Script: `scripts/extract_adhd200_phenotype.py`
+
+```bash
+python skills/adhd200-skill/scripts/extract_adhd200_phenotype.py \
+  --phenotype-dir /path/to/adhd200_raw/phenotype \
+  --output /path/to/adhd200_output/phenotype/merged_phenotype.csv \
+  --columns subject,DX,AGE,SEX,ADHD_Index,Inatt,HyperImp \
+  --imaging-ids /path/to/adhd200_output/bids/participants.tsv
+```
+
+---
+
+## QC Integration
+
+### Script: `scripts/adhd200_qc_summary.py`
+
+```bash
+python skills/adhd200-skill/scripts/adhd200_qc_summary.py \
+  --fmriprep-dir /path/to/adhd200_output/fmriprep \
+  --freesurfer-dir /path/to/adhd200_output/smri/freesurfer \
+  --output /path/to/adhd200_output/qc/qc_summary.csv \
+  --exclude-output /path/to/adhd200_output/qc/exclude_list.csv \
+  --fd-threshold 0.3
+```
+
+---
+
+## Recommended Output Layout
+All assets should be organized under `./adhd200_output/`:
+- `adhd200_output/raw/` (downloaded original files)
+- `adhd200_output/bids/` (staged BIDS data)
+- `adhd200_output/smri/` (links or copies from `smri_output/`)
+- `adhd200_output/fmri/` (links or copies from `fmri_output/`)
+- `adhd200_output/phenotype/` (merged phenotype tables)
+- `adhd200_output/qc/` (QC summaries and exclusion lists)
+- `adhd200_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 ADHD-200 data staging or organization.
+
+- If the task starts from raw ADHD-200 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 ADHD-200 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
+- ADHD-200 has heterogeneous acquisition parameters across 8 sites; site effects must be addressed in analysis.
+- ADHD-200 subject IDs are numeric and vary in length across sites.
+- Diagnosis labels vary by site (ADHD-combined, ADHD-inattentive, ADHD-hyperactive, typically developing).
+- ADHD-200 data does not include task-fMRI; only resting-state fMRI is available.
+- `adhd200-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 ADHD-200 workflow.
+- User asks to download ADHD-200 data and then run sMRI/rs-fMRI processing.
+- User needs BIDS staging for raw ADHD-200 NIfTI files.
+- User asks to extract and merge ADHD-200 phenotype tables.
+- User needs ADHD-200-specific QC summaries and exclusion lists.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill`
+- `fmri-skill`
+- `bids-organizer`
+- `fmriprep-tool`
+- `freesurfer-tool`
+- `brain_gnn`
+- `dependency-planner`
+- `conda-env-manager`
+- `claw-shell`
+
+---
+
+## Reference
+- ADHD-200: https://fcon_1000.projects.nitrc.org/indi/adhd200/
+- BIDS spec: https://bids.neuroimaging.io/
+
+Created At: 2026-05-06 01:50 HKT
+Last Updated At: 2026-05-06 01:50 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/adhd200-skill/scripts/adhd200_qc_summary.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries and exclusion lists for ADHD-200."""
+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 generate_qc_summary(fmriprep_qc: Dict, fd_threshold: float, max_fd_threshold: float) -> Tuple["pd.DataFrame", List[str]]:
+    rows = []
+    excluded = []
+    for sub_id in sorted(fmriprep_qc.keys()):
+        fp = fmriprep_qc[sub_id]
+        reasons = []
+        if fp.get("mean_fd", 0) > fd_threshold:
+            reasons.append(f"mean_fd={fp['mean_fd']:.3f}>{fd_threshold}")
+        if fp.get("max_fd", 0) > max_fd_threshold:
+            reasons.append(f"max_fd={fp['max_fd']:.3f}>{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)
+    return pd.DataFrame(rows), excluded
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate ADHD-200 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
+
+    summary_df, excluded = generate_qc_summary(fmriprep_qc, args.fd_threshold, args.max_fd_threshold)
+    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/adhd200-skill/scripts/extract_adhd200_phenotype.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Extract and merge ADHD-200 phenotype tables for downstream analysis."""
+import argparse
+import csv
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+try:
+    import pandas as pd
+except ImportError:
+    print("Error: pandas is required. Install with: pip install pandas", 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",
+    "AGE_AT_SCAN": "age",
+    "SEX": "sex",
+    "ADHD_Index": "adhd_index",
+    "Inatt": "inattention",
+    "HyperImp": "hyperactivity",
+    "SITE_ID": "site",
+    "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 read_phenotype_file(file_path: Path) -> Optional["pd.DataFrame"]:
+    try:
+        return pd.read_csv(file_path, sep=None, engine="python", low_memory=False)
+    except Exception as e:
+        print(f"[WARN] Failed to read {file_path}: {e}", file=sys.stderr)
+        return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Extract and merge ADHD-200 phenotype tables.")
+    parser.add_argument("--phenotype-dir", help="Directory containing ADHD-200 phenotype CSV files")
+    parser.add_argument("--phenotype-file", help="Direct path to ADHD-200 phenotype CSV file")
+    parser.add_argument("--output", required=True, help="Output path for merged phenotype CSV")
+    parser.add_argument("--columns", help="Comma-separated list of columns to select (default: all)")
+    parser.add_argument("--imaging-ids", help="Path to BIDS participants.tsv for imaging subject filtering")
+    parser.add_argument("--missing-threshold", type=float, default=0.5, help="Drop columns with > this fraction missing")
+    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:
+        df = read_phenotype_file(f)
+        if df is not None and len(df) > 0:
+            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)
+
+    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", suffixes=("", "_dup"))
+            dup_cols = [c for c in merged.columns if c.endswith("_dup")]
+            if dup_cols:
+                merged = merged.drop(columns=dup_cols)
+        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
+
+    if args.columns:
+        requested = [c.strip() for c in args.columns.split(",")]
+        available = [c for c in requested if c in merged.columns]
+        if "subject_id" not in available and "subject_id" in merged.columns:
+            available = ["subject_id"] + available
+        if available:
+            merged = merged[available]
+
+    if args.missing_threshold < 1.0:
+        missing_frac = merged.isnull().mean()
+        cols_to_drop = [c for c in missing_frac[missing_frac > args.missing_threshold].index if c not in ("subject_id", "diagnosis")]
+        if cols_to_drop:
+            merged = merged.drop(columns=cols_to_drop)
+
+    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())

package/skills/06_fMRI_Neuroimaging/adhd200-skill/scripts/reorganize_adhd200.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Reorganize ADHD-200 raw data into BIDS-compliant directory structure.
+
+Handles FCP/INDI-style subject directories, site extraction, and modality
+routing for T1w and rs-fMRI.
+"""
+import argparse
+import csv
+import json
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+SIDECAR_EXTENSIONS = [".json", ".bval", ".bvec", ".tsv"]
+
+ADHD200_SITES = [
+    "Peking", "Brown", "NYU", "KKI", "NeuroImage",
+    "OHSU", "Pitt", "WashU", "Washington",
+]
+
+
+def normalize_subject_id(raw_id: str) -> str:
+    clean = re.sub(r"[^a-zA-Z0-9]", "", str(raw_id).strip())
+    return f"sub-{clean}"
+
+
+def detect_site_from_path(file_path: Path, root_dir: Path) -> str:
+    rel = file_path.relative_to(root_dir)
+    for part in rel.parts:
+        for site in ADHD200_SITES:
+            if site.lower() in part.lower():
+                return site
+    return "unknown"
+
+
+def detect_modality(directory: Path, filename: str) -> Optional[Tuple[str, str]]:
+    name_lower = (directory.name + " " + filename).lower()
+    if any(k in name_lower for k in ["t1w", "t1", "anat", "mprage"]):
+        if "bold" not in name_lower:
+            return ("T1w", "anat")
+    if any(k in name_lower for k in ["rest", "bold", "fmri", "func", "rsfmri"]):
+        return ("task-rest_bold", "func")
+    return None
+
+
+def find_nifti_files(directory: Path) -> List[Path]:
+    return [
+        f for f in directory.rglob("*")
+        if f.is_file() and (f.name.endswith(".nii") or f.name.endswith(".nii.gz"))
+    ]
+
+
+def copy_with_sidecars(src_nifti: Path, dst_dir: Path, dst_stem: str) -> None:
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    ext = ".nii.gz" if src_nifti.name.endswith(".nii.gz") else ".nii"
+    dst_nifti = dst_dir / f"{dst_stem}{ext}"
+    if not dst_nifti.exists():
+        shutil.copy2(str(src_nifti), str(dst_nifti))
+
+    src_stem = src_nifti.name[:-7] if src_nifti.name.endswith(".nii.gz") else src_nifti.name[:-4]
+    for sidecar_ext in SIDECAR_EXTENSIONS:
+        src_sidecar = src_nifti.parent / f"{src_stem}{sidecar_ext}"
+        if src_sidecar.exists():
+            dst_sidecar = dst_dir / f"{dst_stem}{sidecar_ext}"
+            if not dst_sidecar.exists():
+                shutil.copy2(str(src_sidecar), str(dst_sidecar))
+
+
+def write_dataset_description(bids_root: Path) -> None:
+    desc = {
+        "Name": "ADHD-200",
+        "BIDSVersion": "1.8.0",
+        "DatasetType": "raw",
+        "GeneratedBy": [{"Name": "NeuroClaw adhd200-skill", "Version": "1.0.0"}],
+    }
+    (bids_root / "dataset_description.json").write_text(
+        json.dumps(desc, indent=2), encoding="utf-8"
+    )
+
+
+def write_participants_tsv(bids_root: Path, participants: List[Dict[str, str]], phenotype_file: Optional[Path] = None) -> None:
+    phenotype_map: Dict[str, Dict[str, str]] = {}
+    if phenotype_file and phenotype_file.exists():
+        try:
+            with open(phenotype_file, "r", encoding="utf-8") as f:
+                reader = csv.DictReader(f)
+                for row in reader:
+                    sid = row.get("subject", row.get("SUBJECT_ID", row.get("Subject", "")))
+                    if sid:
+                        phenotype_map[normalize_subject_id(sid)] = row
+        except Exception:
+            pass
+
+    tsv_path = bids_root / "participants.tsv"
+    headers = ["participant_id", "site"]
+    if phenotype_map:
+        sample = next(iter(phenotype_map.values()))
+        for col in sample:
+            if col not in headers and col not in ("subject", "SUBJECT_ID", "Subject"):
+                headers.append(col)
+
+    with open(tsv_path, "w", encoding="utf-8", newline="") as f:
+        writer = csv.writer(f, delimiter="\t")
+        writer.writerow(headers)
+        seen = set()
+        for p in participants:
+            pid = p["participant_id"]
+            if pid in seen:
+                continue
+            seen.add(pid)
+            row = [pid, p.get("site", "unknown")]
+            pheno = phenotype_map.get(pid, {})
+            for col in headers[2:]:
+                row.append(pheno.get(col, "n/a"))
+            writer.writerow(row)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Reorganize ADHD-200 raw data into BIDS structure.")
+    parser.add_argument("--input", required=True, help="Path to ADHD-200 raw data directory")
+    parser.add_argument("--output", required=True, help="Path to output BIDS directory")
+    parser.add_argument("--phenotype", help="Path to ADHD-200 phenotype CSV file")
+    parser.add_argument("--dry-run", action="store_true", help="Preview without copying files")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    output_dir = Path(args.output).resolve()
+
+    if not input_dir.exists():
+        print(f"Input directory does not exist: {input_dir}", file=sys.stderr)
+        return 1
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    participants: List[Dict[str, str]] = []
+    converted = skipped = failed = 0
+
+    print(f"{'[DRY RUN] ' if args.dry_run else ''}Starting ADHD-200 reorganization...\n")
+
+    subject_dirs = sorted([p for p in input_dir.iterdir() if p.is_dir() and not p.name.startswith(".")])
+
+    for subject_dir in subject_dirs:
+        site = detect_site_from_path(subject_dir, input_dir)
+        nifti_files = find_nifti_files(subject_dir)
+
+        if not nifti_files:
+            # Treat as site directory
+            for sub_dir in sorted(subject_dir.iterdir()):
+                if not sub_dir.is_dir():
+                    continue
+                sub_label = normalize_subject_id(sub_dir.name)
+                participants.append({"participant_id": sub_label, "site": site})
+                for nifti in find_nifti_files(sub_dir):
+                    result = detect_modality(nifti.parent, nifti.name)
+                    if result is None:
+                        result = detect_modality(sub_dir, nifti.name)
+                    if result is None:
+                        failed += 1
+                        continue
+                    bids_suffix, bids_folder = result
+                    bids_sub_dir = output_dir / sub_label / "ses-1" / bids_folder
+                    dst_stem = f"{sub_label}_ses-1_{bids_suffix}"
+                    if (bids_sub_dir / f"{dst_stem}.nii.gz").exists():
+                        skipped += 1
+                        continue
+                    if args.dry_run:
+                        print(f"[DRY] {sub_label}/ses-1/{bids_folder}/{dst_stem}")
+                    else:
+                        copy_with_sidecars(nifti, bids_sub_dir, dst_stem)
+                        print(f"[OK] {sub_label} ({site}) / {bids_folder} / {dst_stem}")
+                    converted += 1
+        else:
+            sub_label = normalize_subject_id(subject_dir.name)
+            participants.append({"participant_id": sub_label, "site": site})
+            for nifti in nifti_files:
+                result = detect_modality(nifti.parent, nifti.name)
+                if result is None:
+                    result = detect_modality(subject_dir, nifti.name)
+                if result is None:
+                    failed += 1
+                    continue
+                bids_suffix, bids_folder = result
+                bids_sub_dir = output_dir / sub_label / "ses-1" / bids_folder
+                dst_stem = f"{sub_label}_ses-1_{bids_suffix}"
+                if (bids_sub_dir / f"{dst_stem}.nii.gz").exists():
+                    skipped += 1
+                    continue
+                if args.dry_run:
+                    print(f"[DRY] {sub_label}/ses-1/{bids_folder}/{dst_stem}")
+                else:
+                    copy_with_sidecars(nifti, bids_sub_dir, dst_stem)
+                    print(f"[OK] {sub_label} ({site}) / {bids_folder} / {dst_stem}")
+                converted += 1
+
+    if not args.dry_run and converted > 0:
+        write_dataset_description(output_dir)
+        phenotype_path = Path(args.phenotype).resolve() if args.phenotype else None
+        write_participants_tsv(output_dir, participants, phenotype_path)
+
+    print(f"\nDone. Converted={converted}, Skipped={skipped}, Failed={failed}")
+    return 0 if failed == 0 else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())