@brainpilot/skills 0.0.6 → 0.0.8

package/skills/06_fMRI_Neuroimaging/aomic-skill/scripts/reorganize_aomic.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""Validate and reorganize AOMIC data into BIDS-compliant directory structure.
+
+AOMIC (Amsterdam Open MRI Collection) data is typically already in BIDS format.
+This script validates structure, handles edge cases, and normalizes across
+sub-datasets (ID1000, PIOP1, PIOP2).
+"""
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# AOMIC task names recognized in BIDS
+AOMIC_TASKS = [
+    "rest",
+    "emotion",
+    "gambling",
+    "motor",
+    "language",
+    "workingmemory",
+    "stroop",
+]
+
+SIDECAR_EXTENSIONS = [".json", ".bval", ".bvec", ".tsv", ".txt"]
+
+
+def validate_subject_id(subject_dir_name: str) -> Optional[str]:
+    """Validate and normalize AOMIC subject ID to BIDS label.
+
+    AOMIC uses sub-XXXX format already.
+    """
+    name = subject_dir_name.strip()
+    if name.startswith("sub-"):
+        label = name[4:]
+    else:
+        label = name
+
+    # Must be alphanumeric
+    clean = re.sub(r"[^a-zA-Z0-9]", "", label)
+    if not clean:
+        return None
+    return f"sub-{clean}"
+
+
+def detect_task_from_filename(filename: str) -> Optional[str]:
+    """Extract BIDS task name from filename."""
+    match = re.search(r"task-([a-zA-Z0-9]+)", filename)
+    if match:
+        return match.group(1).lower()
+    return None
+
+
+def validate_bids_filename(filename: str) -> bool:
+    """Check if filename follows BIDS naming conventions."""
+    # Must have sub- prefix for subject
+    if not re.search(r"sub-[a-zA-Z0-9]+", filename):
+        return False
+    # Must end with known extensions
+    valid_exts = [".nii", ".nii.gz", ".json", ".tsv", ".bval", ".bvec", ".txt", ".eeg", ".vhdr", ".vmrk"]
+    return any(filename.endswith(ext) for ext in valid_exts)
+
+
+def find_nifti_files(directory: Path) -> List[Path]:
+    """Find all NIfTI files in a directory."""
+    results = []
+    for f in sorted(directory.rglob("*")):
+        if f.is_file() and (f.name.endswith(".nii") or f.name.endswith(".nii.gz")):
+            results.append(f)
+    return results
+
+
+def copy_with_sidecars(src_nifti: Path, dst_dir: Path, dst_stem: str) -> List[Path]:
+    """Copy NIfTI file and its sidecar files to destination."""
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    copied = []
+
+    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))
+    copied.append(dst_nifti)
+
+    src_stem = src_nifti.name
+    if src_stem.endswith(".nii.gz"):
+        src_stem = src_stem[:-7]
+    elif src_stem.endswith(".nii"):
+        src_stem = src_stem[:-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))
+            copied.append(dst_sidecar)
+
+    return copied
+
+
+def write_dataset_description(bids_root: Path, sub_dataset: str = "AOMIC") -> None:
+    """Write BIDS dataset_description.json."""
+    desc = {
+        "Name": f"Amsterdam Open MRI Collection ({sub_dataset})",
+        "BIDSVersion": "1.8.0",
+        "DatasetType": "raw",
+        "GeneratedBy": [
+            {
+                "Name": "NeuroClaw aomic-skill",
+                "Description": f"AOMIC ({sub_dataset}) data validated and reorganized to BIDS structure",
+                "Version": "1.0.0",
+            }
+        ],
+    }
+    desc_path = bids_root / "dataset_description.json"
+    with open(desc_path, "w", encoding="utf-8") as f:
+        json.dump(desc, f, indent=2, ensure_ascii=False)
+    print(f"[OK] Wrote {desc_path}")
+
+
+def write_participants_tsv(bids_root: Path, subject_ids: List[str]) -> None:
+    """Write BIDS participants.tsv header."""
+    tsv_path = bids_root / "participants.tsv"
+    with open(tsv_path, "w", encoding="utf-8") as f:
+        f.write("participant_id\n")
+        for sid in sorted(set(subject_ids)):
+            f.write(f"{sid}\n")
+    print(f"[OK] Wrote {tsv_path} ({len(set(subject_ids))} participants)")
+
+
+def process_aomic_subject(
+    subject_dir: Path,
+    bids_root: Path,
+    sub_label: str,
+    dry_run: bool = False,
+    copy_mode: bool = False,
+) -> Tuple[int, int, int]:
+    """Process a single AOMIC subject directory.
+
+    AOMIC data is typically already in BIDS layout. This function validates
+    and optionally copies/reorganizes.
+
+    Returns (converted, skipped, failed).
+    """
+    converted = 0
+    skipped = 0
+    failed = 0
+
+    # Check for standard BIDS subdirectories
+    anat_dir = subject_dir / "anat"
+    func_dir = subject_dir / "func"
+    dwi_dir = subject_dir / "dwi"
+
+    nifti_files = find_nifti_files(subject_dir)
+
+    if not nifti_files:
+        print(f"[WARN] {sub_label}: no NIfTI files found")
+        return 0, 0, 1
+
+    for nifti in nifti_files:
+        # Determine BIDS folder from relative path
+        try:
+            rel_path = nifti.relative_to(subject_dir)
+        except ValueError:
+            rel_path = Path(nifti.name)
+
+        parts = rel_path.parts
+        if len(parts) > 1:
+            bids_folder = parts[0]  # anat, func, dwi
+            bids_filename = parts[-1]
+        else:
+            bids_filename = nifti.name
+            # Try to detect folder from filename
+            if "T1w" in bids_filename or "T2w" in bids_filename:
+                bids_folder = "anat"
+            elif "bold" in bids_filename or "task-" in bids_filename:
+                bids_folder = "func"
+            elif "dwi" in bids_filename:
+                bids_folder = "dwi"
+            else:
+                bids_folder = "anat"
+
+        # Ensure filename has subject prefix
+        if not bids_filename.startswith(sub_label):
+            # Try to fix
+            bids_filename = f"{sub_label}_{bids_filename.split('_', 1)[-1]}" if "_" in bids_filename else f"{sub_label}_{bids_filename}"
+
+        dst_dir = bids_root / sub_label / bids_folder
+        dst_stem = bids_filename.rsplit(".nii", 1)[0]
+        if dst_stem.endswith("."):
+            dst_stem = dst_stem[:-1]
+
+        ext = ".nii.gz" if nifti.name.endswith(".nii.gz") else ".nii"
+        if (dst_dir / f"{dst_stem}{ext}").exists():
+            skipped += 1
+            continue
+
+        if dry_run:
+            print(f"[DRY] {sub_label}/{bids_folder}/{dst_stem}")
+            converted += 1
+        elif copy_mode:
+            copy_with_sidecars(nifti, dst_dir, dst_stem)
+            print(f"[OK] {sub_label}/{bids_folder}/{dst_stem}")
+            converted += 1
+        else:
+            # Validation-only mode
+            if validate_bids_filename(bids_filename):
+                print(f"[VALID] {sub_label}/{bids_folder}/{bids_filename}")
+                converted += 1
+            else:
+                print(f"[WARN] {sub_label}/{bids_folder}/{bids_filename}: non-standard naming")
+                failed += 1
+
+    return converted, skipped, failed
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate and reorganize AOMIC data into BIDS-compliant structure."
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        help="Path to AOMIC data directory",
+    )
+    parser.add_argument(
+        "--output",
+        required=True,
+        help="Path to output BIDS directory",
+    )
+    parser.add_argument(
+        "--sub-dataset",
+        default="ID1000",
+        choices=["ID1000", "PIOP1", "PIOP2", "all"],
+        help="AOMIC sub-dataset (default: ID1000)",
+    )
+    parser.add_argument(
+        "--participants-file",
+        help="Optional: path to phenotype file for participant metadata",
+    )
+    parser.add_argument(
+        "--copy",
+        action="store_true",
+        help="Copy files to output directory (default: validation only)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview without processing files",
+    )
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    output_dir = Path(args.output).resolve()
+
+    if not input_dir.exists() or not input_dir.is_dir():
+        print(f"Input directory does not exist: {input_dir}", file=sys.stderr)
+        return 1
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    participants: List[str] = []
+
+    print(f"Sub-dataset: {args.sub_dataset}")
+    print(f"Input:  {input_dir}")
+    print(f"Output: {output_dir}")
+    print(f"Mode:   {'DRY RUN' if args.dry_run else 'COPY' if args.copy else 'VALIDATE'}")
+    print()
+
+    # Find subject directories
+    subject_dirs = sorted(
+        [p for p in input_dir.iterdir() if p.is_dir() and (p.name.startswith("sub-") or re.match(r"^\d+$", p.name))]
+    )
+
+    if not subject_dirs:
+        # Try nested structure (e.g., ID1000/sub-0001/)
+        for child in sorted(input_dir.iterdir()):
+            if child.is_dir():
+                nested = sorted(
+                    [p for p in child.iterdir() if p.is_dir() and (p.name.startswith("sub-") or re.match(r"^\d+$", p.name))]
+                )
+                subject_dirs.extend(nested)
+
+    if not subject_dirs:
+        print("[ERROR] No subject directories found.", file=sys.stderr)
+        return 1
+
+    print(f"Found {len(subject_dirs)} subject directories\n")
+
+    total_converted = 0
+    total_skipped = 0
+    total_failed = 0
+
+    for subject_dir in subject_dirs:
+        sub_label = validate_subject_id(subject_dir.name)
+        if not sub_label:
+            print(f"[WARN] Skipping invalid directory: {subject_dir.name}")
+            total_failed += 1
+            continue
+
+        participants.append(sub_label)
+        converted, skipped, failed = process_aomic_subject(
+            subject_dir, output_dir, sub_label, args.dry_run, args.copy
+        )
+        total_converted += converted
+        total_skipped += skipped
+        total_failed += failed
+
+    # Write BIDS metadata
+    if not args.dry_run and (args.copy or total_converted > 0):
+        write_dataset_description(output_dir, args.sub_dataset)
+        write_participants_tsv(output_dir, participants)
+
+    print(f"\nDone. Converted={total_converted}, Skipped={total_skipped}, Failed={total_failed}")
+    return 0 if total_failed == 0 else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,168 @@
+---
+name: asl-skill
+description: "Use this skill whenever the user wants to process Arterial Spin Labeling (ASL) perfusion MRI data including CBF (cerebral blood flow) quantification, ASL preprocessing (motion correction, partial volume correction, M0 normalization), or ASL-based brain perfusion analysis. Triggers include: 'ASL', 'ASL processing', 'CBF', 'cerebral blood flow', 'perfusion MRI', 'arterial spin labeling', 'pCASL', 'CASL', 'PASL', or any request involving ASL perfusion data."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: subagent
+skill_type: modality
+dependencies:
+  - fsl-tool
+  - nibabel-skill
+  - claw-shell
+complementary_skills:
+  - smri-skill
+  - fmri-skill
+---
+# ASL Skill (Modality Layer)
+
+## Overview
+
+`asl-skill` is the NeuroClaw **modality-layer** interface skill responsible for all Arterial Spin Labeling (ASL) perfusion MRI data processing tasks.
+
+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: `fsl-tool`, `nibabel-skill`, and `claw-shell`.
+- Companion scripts in `scripts/` provide reference implementations for CBF quantification.
+
+**Core workflow (never bypassed):**
+1. Identify input ASL data and labeling strategy (pCASL, CASL, or PASL).
+2. Ensure T1w structural data is available (via `smri-skill` if not yet processed).
+3. Generate a **numbered execution plan** clearly stating WHAT needs to be done and which tool skill will handle each step.
+4. Present the full plan, estimated runtime, resource requirements, and risks to the user and wait for explicit confirmation ("YES" / "execute" / "proceed").
+5. On confirmation, delegate every step to the appropriate skill via `claw-shell`.
+6. After execution, save all outputs in a clean directory structure (`asl_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference (Common ASL Tasks)
+
+| Task | What needs to be done | Delegate to which tool skill | Expected output |
+|---|---|---|---|
+| ASL preprocessing | Motion correction, masking, registration to T1w | `fsl-tool` (ASL_PREPCORE) | Preprocessed ASL in T1w space |
+| M0 normalization | Divide ASL difference image by M0 reference image to get perfusion signal | `fsl-tool` or `scripts/compute_cbf.py` | Normalized perfusion map |
+| CBF quantification | Convert perfusion signal to absolute CBF (mL/100g/min) using Buxton model | `scripts/compute_cbf.py` | CBF map (NIfTI) + ROI summary (CSV) |
+| Partial volume correction | Correct CBF for gray/white matter partial volume effects | `fsl-tool` + tissue segmentation | PVC-corrected CBF map |
+| ASL-to-MNI normalization | Warp CBF map to MNI152 template for group analysis | `fsl-tool` (FNIRT) or `smri-skill` | CBF in MNI152 space |
+| ROI-based CBF extraction | Extract mean CBF from atlas-defined ROIs | `fsl-tool` + atlas | Per-region CBF values (CSV) |
+| Quality control | Check for outliers, low SNR, motion artifacts in ASL series | `scripts/compute_cbf.py` (--qc) | QC report |
+
+---
+
+## ASL Labeling Strategies
+
+| Strategy | Description | Typical Parameters |
+|---|---|---|
+| **pCASL** (pseudo-Continuous ASL) | Most common; single PLD, good SNR | Label duration: 1.5–2.0 s, PLD: 1.5–2.0 s |
+| **CASL** (Continuous ASL) | Longer labeling, higher SNR but more sensitive to transit effects | Label duration: 2–4 s, PLD: 1–2 s |
+| **PASL** (Pulsed ASL) | Short labeling, lower SNR, no separate M0 needed (QUIPSS II) | Bolus thickness: 10–15 cm, TI1/TI2: 700/1800 ms |
+
+---
+
+## Core CBF Quantification Model
+
+The Buxton single-compartment model for pCASL:
+
+```
+CBF = (6000 * ΔM * λ) / (2 * α * M0 * T1b * (exp(-w/T1b) - exp(-(τ+w)/T1b)))   [mL/100g/min]
+```
+
+Where:
+- ΔM = ASL difference image (control - label)
+- M0 = equilibrium magnetization of arterial blood
+- λ = blood-tissue water partition coefficient (0.9 mL/g)
+- α = labeling efficiency (0.85 for pCASL, 0.95 for CASL, 0.98 for PASL)
+- T1b = T1 of arterial blood at 3T (~1.65 s) or 1.5T (~1.35 s)
+- w = post-labeling delay (PLD)
+- τ = label duration
+
+---
+
+## Scripts
+
+### `scripts/compute_cbf.py`
+Computes CBF maps from ASL difference images and M0 reference.
+
+```bash
+python skills/asl-skill/scripts/compute_cbf.py \
+  --diff /path/to/asl_diff.nii.gz \
+  --m0 /path/to/m0_reference.nii.gz \
+  --output /path/to/asl_output/cbf_map.nii.gz \
+  --roi-summary /path/to/asl_output/cbf_roi.csv \
+  --roi-atlas /path/to/atlas_in_asl_space.nii.gz \
+  --label-strategy pcasl \
+  --pld 1.8 \
+  --label-duration 1.8 \
+  --field-strength 3.0
+```
+
+---
+
+## Standard Output Layout
+
+```
+asl_output/
+├── preprocessed/          # Motion-corrected, registered ASL
+├── cbf/                   # CBF maps
+│   ├── cbf_map.nii.gz
+│   ├── cbf_roi.csv
+│   └── cbf_mni.nii.gz    # (if normalization requested)
+├── pvc/                   # Partial volume corrected CBF (if requested)
+├── qc/                    # Quality control reports
+│   └── asl_qc_report.csv
+└── logs/
+```
+
+---
+
+## Installation (Handled by dependency-planner)
+
+No manual installation required at this layer.
+When first used, `asl-skill` automatically calls `dependency-planner` to ensure `fsl-tool`, `nibabel-skill`, and `claw-shell` are ready.
+
+---
+
+## Important Notes & Limitations
+
+- ASL has inherently low SNR compared to BOLD fMRI; averaging multiple control-label pairs is recommended.
+- M0 image is required for absolute CBF quantification; if absent, only relative CBF can be computed.
+- PLD and labeling duration must be known from the acquisition protocol; incorrect values invalidate CBF.
+- At 3T, T1b ≈ 1.65 s; at 1.5T, T1b ≈ 1.35 s.
+- Partial volume correction is important for ASL due to its low resolution (~3–4 mm).
+- ASLPrep (https://aslprep.readthedocs.io/) is the recommended automated pipeline for large cohorts.
+- This skill is for research workflows; not for clinical decision-making.
+
+---
+
+## When to Call This Skill
+
+- After `smri-skill` when T1w structural preprocessing is complete and ASL data needs processing.
+- When the user needs CBF quantification from pCASL, CASL, or PASL data.
+- When ASL-to-T1w coregistration or normalization to MNI space is required.
+- When partial volume correction is requested for ASL perfusion analysis.
+- When dataset skills (e.g., PNC) delegate ASL processing.
+
+---
+
+## Complementary / Related Skills
+
+- `smri-skill` → T1w structural preprocessing (brain extraction, tissue segmentation for PVC)
+- `fmri-skill` → if ASL is used alongside BOLD for multimodal analysis
+- `fsl-tool` → ASL_PREPCORE (preprocessing), FLIRT/FNIRT (registration/normalization), BASIL (CBF quantification)
+- `nibabel-skill` → NIfTI I/O for mask manipulation
+- `nilearn-tool` → ROI-based CBF extraction
+- `brain-visualization` → CBF map visualization
+
+---
+
+## Reference
+- Alsop et al. (2015): Recommended implementation of ASL (Magnetic Resonance in Medicine)
+- Buxton et al. (1998): General kinetic model for ASL (Journal of Cerebral Blood Flow & Metabolism)
+- ASLPrep: https://aslprep.readthedocs.io/
+- FSL BASIL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BASIL
+- BIDS ASL extension: https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/11-arterial-spin-labeling.html
+
+Created At: 2026-05-06 12:19 HKT
+Last Updated At: 2026-05-06 12:19 HKT
+Author: chengwang96