@brainpilot/skills 0.0.6 → 0.0.8

package/skills/06_fMRI_Neuroimaging/mnd-skill/scripts/validate_mnd.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Validate MND BIDS structure and generate compliance report.
+
+Checks directory structure, modality completeness, and participant group labeling.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+# Expected modalities for MND
+EXPECTED_MODALITIES = {
+    "func": ["task-rest_bold", "task-motor_bold"],
+}
+
+
+def validate_subject(subject_dir: Path) -> Dict[str, any]:
+    """Validate a single subject's BIDS structure."""
+    report = {
+        "subject": subject_dir.name,
+        "func_complete": False,
+        "rs_fMRI_present": False,
+        "task_fMRI_present": False,
+        "missing_files": [],
+        "warnings": [],
+    }
+
+    # Check func
+    func_dir = subject_dir / "func"
+    if func_dir.exists():
+        rest_bold = list(func_dir.glob("*_task-rest_bold.nii.gz"))
+        motor_bold = list(func_dir.glob("*_task-motor_bold.nii.gz"))
+
+        report["rs_fMRI_present"] = len(rest_bold) > 0
+        report["task_fMRI_present"] = len(motor_bold) > 0
+        report["func_complete"] = report["rs_fMRI_present"] and report["task_fMRI_present"]
+
+        if not rest_bold:
+            report["missing_files"].append("func/*_task-rest_bold.nii.gz")
+        if not motor_bold:
+            report["missing_files"].append("func/*_task-motor_bold.nii.gz")
+    else:
+        report["missing_files"].append("func/")
+
+    # Check anat (optional for MND)
+    anat_dir = subject_dir / "anat"
+    if not anat_dir.exists():
+        report["warnings"].append("No anat directory (optional for MND)")
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate MND BIDS structure."
+    )
+    parser.add_argument("--input", required=True, help="Path to MND BIDS directory")
+    parser.add_argument("--output", required=True, help="Output path for validation CSV")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    if not input_dir.exists():
+        print(f"Input directory not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    # Find subjects
+    subjects = sorted([d for d in input_dir.glob("sub-*") if d.is_dir()])
+    print(f"Found {len(subjects)} subjects in {input_dir}")
+
+    if not subjects:
+        print("[ERROR] No subjects found.", file=sys.stderr)
+        return 1
+
+    # Validate each subject
+    results = []
+    for sub_dir in subjects:
+        report = validate_subject(sub_dir)
+        results.append(report)
+
+    # Write output
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fieldnames = ["subject", "func_complete", "rs_fMRI_present", "task_fMRI_present", "missing_files", "warnings"]
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        for r in results:
+            r["missing_files"] = "; ".join(r["missing_files"])
+            r["warnings"] = "; ".join(r["warnings"])
+            writer.writerow(r)
+
+    # Summary
+    complete_subjects = sum(1 for r in results if r["func_complete"])
+    print(f"\nValidation Summary:")
+    print(f"  Total subjects: {len(results)}")
+    print(f"  Complete (rs-fMRI + task-fMRI): {complete_subjects}")
+    print(f"  With rs-fMRI: {sum(1 for r in results if r['rs_fMRI_present'])}")
+    print(f"  With task-fMRI: {sum(1 for r in results if r['task_fMRI_present'])}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,203 @@
+---
+name: mschallenge-skill
+description: "Use this skill whenever the user wants an end-to-end workflow for the Longitudinal MS Lesion Segmentation Challenge dataset, including data validation, multimodal processing of T1w, T2w, FLAIR, and PD, lesion segmentation, and QC integration. Triggers include: 'MS Lesion Challenge', 'MS Lesion', 'ISBI MS', 'longitudinal MS', 'multiple sclerosis lesion', or any request to run the MS lesion segmentation pipeline."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: subagent
+skill_type: dataset
+dependencies:
+  - smri-skill
+  - nibabel-skill
+  - claw-shell
+complementary_skills:
+  - brain-visualization
+---
+# MS Challenge Skill (Dataset-Orchestration Layer)
+
+## Overview
+
+`mschallenge-skill` is the NeuroClaw orchestration skill for the **Longitudinal MS Lesion Segmentation Challenge** 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 validation, lesion analysis, and QC.
+
+**Core workflow (never bypassed):**
+1. Identify input MS Challenge 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 (`mschallenge_output/`).
+
+**Research use only.**
+
+---
+
+## Quick Reference
+
+| Task | What needs to be done | Delegate to | Expected output |
+|---|---|---|---|
+| Data validation | Validate MS Challenge directory structure | `scripts/validate_mschallenge.py` | Validation report |
+| sMRI processing | Brain extraction, tissue segmentation | `smri-skill` | `smri_output/` derivatives |
+| Lesion analysis | Lesion volume, count, location analysis | `scripts/analyze_lesions.py` | Lesion statistics CSV |
+| Longitudinal analysis | Lesion change tracking across timepoints | `scripts/longitudinal_lesion.py` | Longitudinal change report |
+| QC summary | Per-subject quality control | `scripts/mschallenge_qc_summary.py` | QC summary + exclusion list |
+
+---
+
+## Dataset Characteristics
+
+- **Origin**: ISBI 2015 Longitudinal MS Lesion Segmentation Challenge
+- **Training**: 5 subjects, each with 2 timepoints (longitudinal)
+- **Testing**: 14 subjects (hidden ground truth), 4-6 timepoints each
+- **Modalities**: T1w, T2w, FLAIR, PD (co-registered)
+- **Ground truth**: Manual lesion segmentation masks (training only)
+- **Resolution**: ~0.5 × 0.5 × 0.5 mm (isotropic)
+- **Preprocessing**: Skull-stripped, co-registered to common space
+- **Reference**: Carass et al. (2017), NeuroImage
+
+---
+
+## Supported Modalities
+
+| Modality | Description | Use in MS |
+|---|---|---|
+| T1w | T1-weighted structural | Brain atrophy, gray matter lesions |
+| T2w | T2-weighted | White matter lesion detection |
+| FLAIR | Fluid-Attenuated Inversion Recovery | Periventricular lesion detection |
+| PD | Proton Density | Complementary lesion contrast |
+
+---
+
+## Directory Structure (Native)
+
+```
+training/
+├── subject01/
+│   ├── time01/
+│   │   ├── subject01_time01_T1.nii.gz
+│   │   ├── subject01_time01_T2.nii.gz
+│   │   ├── subject01_time01_FLAIR.nii.gz
+│   │   ├── subject01_time01_PD.nii.gz
+│   │   └── subject01_time01_lesion.nii.gz  (ground truth)
+│   └── time02/
+│       └── ...
+```
+
+---
+
+## BIDS Preparation
+
+### Script: `scripts/validate_mschallenge.py`
+
+Validates MS Challenge directory structure and generates a compliance report.
+
+```bash
+python skills/mschallenge-skill/scripts/validate_mschallenge.py \
+  --input /path/to/MSChallenge/training \
+  --output /path/to/mschallenge_output/qc/validation.csv
+```
+
+Features:
+- Directory structure validation
+- Modality completeness check (T1w, T2w, FLAIR, PD)
+- Ground truth mask presence verification
+- Longitudinal timepoint consistency
+- Missing data identification
+
+---
+
+## Core Workflow (Never Bypassed)
+
+1. Identify user target: full MS Challenge processing, lesion analysis, or validation 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 data validation using `scripts/validate_mschallenge.py`.
+5. Delegate to `smri-skill` for structural MRI processing.
+6. If lesion analysis is requested, run `scripts/analyze_lesions.py`.
+7. If longitudinal analysis is requested, run `scripts/longitudinal_lesion.py`.
+8. If QC summary is requested, run `scripts/mschallenge_qc_summary.py`.
+9. Save outputs into `mschallenge_output/`.
+
+---
+
+## Modality Processing Delegation
+
+| Modality | Delegated skill | Typical tasks | Main outputs |
+|---|---|---|---|
+| sMRI (T1w/T2w/FLAIR/PD) | `smri-skill` | brain extraction, tissue segmentation | `smri_output/` derivatives |
+| Lesion masks | `nibabel-skill` | lesion volume, count, location | Lesion statistics |
+
+---
+
+## Standard Output Layout
+
+```
+mschallenge_output/
+├── raw/                    # Original MS Challenge files
+├── validation/             # Validation reports
+├── smri/                   # Structural MRI derivatives
+├── lesions/                # Lesion analysis results
+│   ├── lesion_stats.csv
+│   └── longitudinal_change.csv
+├── qc/                     # QC summaries and exclusion lists
+└── logs/                   # Processing logs
+```
+
+---
+
+## Benchmark Adapter Guidance
+
+For benchmark-style prompts, do not force the full orchestration when the task only asks for local MS Challenge data validation.
+
+- If the task starts from MS Challenge data already present on disk and only asks for validation:
+  - Skip the download stage
+  - Default to the narrow path `local MS Challenge discovery -> validation -> report`
+- In benchmark mode, do not require explicit confirmation before presenting the validation 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
+- MS Challenge is a longitudinal dataset; consider timepoint effects in analysis.
+- Ground truth masks are only available for training subjects.
+- All images are preprocessed (skull-stripped, co-registered).
+- Lesion segmentation is the primary task; standard brain morphometry may be affected by lesions.
+- The challenge is designed for benchmarking; results should be compared with published baselines.
+- `mschallenge-skill` is orchestration-only; detailed preprocessing logic remains in modality skills.
+
+---
+
+## When to Call This Skill
+- User asks for end-to-end MS Lesion Challenge workflow.
+- User asks to validate MS Challenge data structure.
+- User asks for lesion volume and count analysis.
+- User asks for longitudinal lesion change tracking.
+- User asks for MS lesion segmentation benchmarking.
+
+---
+
+## Complementary / Related Skills
+- `smri-skill` → structural MRI preprocessing
+- `nibabel-skill` → NIfTI I/O and mask manipulation
+- `brain-visualization` → lesion overlay visualization
+- `dependency-planner` → dependency resolution
+- `conda-env-manager` → environment management
+- `claw-shell` → command execution
+
+---
+
+## Reference
+- Carass et al. (2017): Longitudinal multiple sclerosis lesion segmentation: Resource and challenge. NeuroImage.
+- ISBI 2015 MS Lesion Challenge: https://smart-stats-tools.org/lesion-challenge
+
+Created At: 2026-05-06 13:31 HKT
+Last Updated At: 2026-05-06 13:31 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/mschallenge-skill/scripts/analyze_lesions.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Analyze lesion masks from MS Lesion Challenge data.
+
+Computes lesion volume, count, and location statistics from binary lesion masks.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+try:
+    import numpy as np
+except ImportError:
+    print("Error: numpy is required.", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    import nibabel as nib
+except ImportError:
+    print("Error: nibabel is required.", file=sys.stderr)
+    sys.exit(1)
+
+
+def count_lesions(lesion_data: np.ndarray) -> int:
+    """Count connected components (lesions) in binary mask."""
+    try:
+        from scipy.ndimage import label
+        labeled, num_features = label(lesion_data)
+        return num_features
+    except ImportError:
+        # Fallback: count unique non-zero regions
+        return int(np.sum(lesion_data > 0) > 0)
+
+
+def compute_lesion_volume(lesion_data: np.ndarray, voxel_size: tuple) -> float:
+    """Compute total lesion volume in mm³."""
+    n_voxels = np.sum(lesion_data > 0)
+    voxel_volume = np.prod(voxel_size)
+    return float(n_voxels * voxel_volume)
+
+
+def analyze_lesion_mask(mask_path: Path) -> Dict[str, float]:
+    """Analyze a single lesion mask."""
+    img = nib.load(str(mask_path))
+    data = img.get_fdata()
+    voxel_size = img.header.get_zooms()[:3]
+
+    n_lesions = count_lesions(data)
+    volume_mm3 = compute_lesion_volume(data, voxel_size)
+    volume_ml = volume_mm3 / 1000.0  # Convert mm³ to mL
+
+    return {
+        "n_lesions": n_lesions,
+        "volume_mm3": volume_mm3,
+        "volume_ml": volume_ml,
+        "n_voxels": int(np.sum(data > 0)),
+        "voxel_size": str(voxel_size),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Analyze lesion masks from MS Challenge data."
+    )
+    parser.add_argument("--input", required=True, help="Path to directory with lesion masks")
+    parser.add_argument("--output", required=True, help="Output path for lesion statistics CSV")
+    parser.add_argument("--pattern", default="*_lesion.nii.gz",
+                        help="Glob pattern for lesion masks (default: *_lesion.nii.gz)")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    if not input_dir.exists():
+        print(f"Input directory not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    # Find lesion masks
+    mask_files = sorted(input_dir.rglob(args.pattern))
+    print(f"Found {len(mask_files)} lesion masks")
+
+    if not mask_files:
+        print("[WARN] No lesion masks found.", file=sys.stderr)
+        return 1
+
+    # Analyze each mask
+    results = []
+    for mask_path in mask_files:
+        try:
+            stats = analyze_lesion_mask(mask_path)
+            stats["file"] = str(mask_path.relative_to(input_dir))
+            results.append(stats)
+        except Exception as e:
+            print(f"[WARN] Error processing {mask_path}: {e}", file=sys.stderr)
+
+    # Write output
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if results:
+        fieldnames = ["file", "n_lesions", "volume_mm3", "volume_ml", "n_voxels", "voxel_size"]
+        with open(output_path, "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=fieldnames)
+            writer.writeheader()
+            writer.writerows(results)
+
+    # Summary
+    total_volume = sum(r["volume_ml"] for r in results)
+    total_lesions = sum(r["n_lesions"] for r in results)
+    print(f"\nLesion Analysis Summary:")
+    print(f"  Masks analyzed: {len(results)}")
+    print(f"  Total lesions: {total_lesions}")
+    print(f"  Total volume: {total_volume:.2f} mL")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/06_fMRI_Neuroimaging/mschallenge-skill/scripts/longitudinal_lesion.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Analyze longitudinal lesion changes across timepoints.
+
+Tracks lesion volume, count, and new/enlarged/resolved lesions
+across multiple timepoints for each subject.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+try:
+    import numpy as np
+except ImportError:
+    print("Error: numpy is required.", file=sys.stderr)
+    sys.exit(1)
+
+try:
+    import nibabel as nib
+except ImportError:
+    print("Error: nibabel is required.", file=sys.stderr)
+    sys.exit(1)
+
+
+def load_lesion_mask(mask_path: Path) -> np.ndarray:
+    """Load lesion mask and return binary data."""
+    img = nib.load(str(mask_path))
+    return (img.get_fdata() > 0).astype(np.uint8)
+
+
+def compute_lesion_changes(mask_t1: np.ndarray, mask_t2: np.ndarray) -> Dict[str, int]:
+    """Compute lesion changes between two timepoints."""
+    # New lesions: present in t2 but not in t1
+    new_lesions = np.sum((mask_t2 > 0) & (mask_t1 == 0))
+    # Resolved lesions: present in t1 but not in t2
+    resolved_lesions = np.sum((mask_t1 > 0) & (mask_t2 == 0))
+    # Stable lesions: present in both
+    stable_lesions = np.sum((mask_t1 > 0) & (mask_t2 > 0))
+    # Enlarged lesions: increased volume (approximate)
+    enlarged_lesions = 0  # Would need connected component analysis
+
+    return {
+        "new_voxels": int(new_lesions),
+        "resolved_voxels": int(resolved_lesions),
+        "stable_voxels": int(stable_lesions),
+        "enlarged_voxels": int(enlarged_lesions),
+    }
+
+
+def analyze_subject(subject_dir: Path) -> Dict[str, any]:
+    """Analyze longitudinal lesion changes for a single subject."""
+    report = {
+        "subject": subject_dir.name,
+        "timepoints": [],
+        "volumes": [],
+        "changes": [],
+    }
+
+    # Find timepoints with lesion masks
+    timepoints = sorted([d for d in subject_dir.iterdir() if d.is_dir()])
+    masks = {}
+
+    for tp_dir in timepoints:
+        lesion_files = list(tp_dir.glob("*_lesion.nii.gz"))
+        if lesion_files:
+            masks[tp_dir.name] = lesion_files[0]
+            report["timepoints"].append(tp_dir.name)
+
+    if len(masks) < 2:
+        report["warning"] = "Need at least 2 timepoints for longitudinal analysis"
+        return report
+
+    # Compute volumes for each timepoint
+    for tp_name in report["timepoints"]:
+        mask_data = load_lesion_mask(masks[tp_name])
+        volume = int(np.sum(mask_data > 0))
+        report["volumes"].append(volume)
+
+    # Compute changes between consecutive timepoints
+    for i in range(len(report["timepoints"]) - 1):
+        tp1 = report["timepoints"][i]
+        tp2 = report["timepoints"][i + 1]
+        mask1 = load_lesion_mask(masks[tp1])
+        mask2 = load_lesion_mask(masks[tp2])
+        changes = compute_lesion_changes(mask1, mask2)
+        changes["from"] = tp1
+        changes["to"] = tp2
+        report["changes"].append(changes)
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Analyze longitudinal lesion changes."
+    )
+    parser.add_argument("--input", required=True, help="Path to MS Challenge directory")
+    parser.add_argument("--output", required=True, help="Output path for longitudinal analysis CSV")
+    args = parser.parse_args()
+
+    input_dir = Path(args.input).resolve()
+    if not input_dir.exists():
+        print(f"Input directory not found: {input_dir}", file=sys.stderr)
+        return 1
+
+    # Find subjects
+    subjects = sorted([d for d in input_dir.iterdir() if d.is_dir()])
+    print(f"Found {len(subjects)} subjects")
+
+    if not subjects:
+        print("[ERROR] No subjects found.", file=sys.stderr)
+        return 1
+
+    # Analyze each subject
+    results = []
+    for sub_dir in subjects:
+        report = analyze_subject(sub_dir)
+        results.append(report)
+
+    # Write output
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        writer.writerow(["subject", "n_timepoints", "volumes", "changes"])
+        for r in results:
+            writer.writerow([
+                r["subject"],
+                len(r["timepoints"]),
+                str(r["volumes"]),
+                str(r["changes"]),
+            ])
+
+    # Summary
+    total_subjects = len(results)
+    subjects_with_changes = sum(1 for r in results if r.get("changes"))
+    print(f"\nLongitudinal Analysis Summary:")
+    print(f"  Subjects: {total_subjects}")
+    print(f"  With longitudinal data: {subjects_with_changes}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())