@brainpilot/skills 0.0.6 → 0.0.8

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Generate per-subject QC summaries for MS Challenge processing.
+
+Checks modality completeness, ground truth presence, and data quality.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+EXPECTED_MODALITIES = ["T1", "T2", "FLAIR", "PD"]
+
+
+def validate_subject(subject_dir: Path, has_ground_truth: bool = True) -> Dict[str, any]:
+    """Validate a single subject's data quality."""
+    report = {
+        "subject": subject_dir.name,
+        "n_timepoints": 0,
+        "modalities_complete": False,
+        "ground_truth_complete": False,
+        "excluded": False,
+        "exclusion_reasons": [],
+    }
+
+    # Find timepoints
+    timepoints = sorted([d for d in subject_dir.iterdir() if d.is_dir()])
+    report["n_timepoints"] = len(timepoints)
+
+    if not timepoints:
+        report["excluded"] = True
+        report["exclusion_reasons"].append("No timepoints found")
+        return report
+
+    # Check modalities
+    all_complete = True
+    for tp_dir in timepoints:
+        for mod in EXPECTED_MODALITIES:
+            mod_files = list(tp_dir.glob(f"*_{mod}.nii.gz"))
+            if not mod_files:
+                mod_files = list(tp_dir.glob(f"*_{mod.lower()}.nii.gz"))
+            if not mod_files:
+                all_complete = False
+
+    report["modalities_complete"] = all_complete
+    if not all_complete:
+        report["exclusion_reasons"].append("Missing modalities")
+
+    # Check ground truth
+    if has_ground_truth:
+        gt_complete = True
+        for tp_dir in timepoints:
+            lesion_files = list(tp_dir.glob("*_lesion.nii.gz"))
+            if not lesion_files:
+                gt_complete = False
+                break
+        report["ground_truth_complete"] = gt_complete
+        if not gt_complete:
+            report["exclusion_reasons"].append("Missing ground truth")
+
+    report["excluded"] = len(report["exclusion_reasons"]) > 0
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate QC summaries for MS Challenge."
+    )
+    parser.add_argument("--input", required=True, help="Path to MS Challenge 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("--no-ground-truth", action="store_true",
+                        help="Skip ground truth validation (for test data)")
+    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
+
+    # Process each subject
+    results = []
+    excluded = []
+    for sub_dir in subjects:
+        report = validate_subject(sub_dir, has_ground_truth=not args.no_ground_truth)
+        results.append(report)
+        if report["excluded"]:
+            excluded.append({
+                "subject": report["subject"],
+                "reasons": "; ".join(report["exclusion_reasons"]),
+            })
+
+    # Write QC summary
+    output_path = Path(args.output).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    fieldnames = ["subject", "n_timepoints", "modalities_complete", "ground_truth_complete", "excluded", "exclusion_reasons"]
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        for r in results:
+            r["exclusion_reasons"] = "; ".join(r["exclusion_reasons"])
+            writer.writerow(r)
+
+    # Write exclusion list
+    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", "reasons"])
+            writer.writeheader()
+            writer.writerows(excluded)
+
+    # Summary
+    print(f"\nQC Summary:")
+    print(f"  Subjects: {len(results)}")
+    print(f"  Excluded: {len(excluded)}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Validate MS Lesion Challenge directory structure.
+
+Checks directory structure, modality completeness, ground truth presence,
+and longitudinal timepoint consistency.
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+# Expected modalities
+EXPECTED_MODALITIES = ["T1", "T2", "FLAIR", "PD"]
+
+
+def validate_subject(subject_dir: Path, has_ground_truth: bool = True) -> Dict[str, any]:
+    """Validate a single subject's directory structure."""
+    report = {
+        "subject": subject_dir.name,
+        "timepoints": [],
+        "modalities_complete": {},
+        "ground_truth_present": {},
+        "missing_files": [],
+        "warnings": [],
+    }
+
+    # Find timepoints
+    timepoints = sorted([d for d in subject_dir.iterdir() if d.is_dir()])
+    report["timepoints"] = [tp.name for tp in timepoints]
+
+    if not timepoints:
+        report["warnings"].append("No timepoints found")
+        return report
+
+    for tp_dir in timepoints:
+        tp_name = tp_dir.name
+        report["modalities_complete"][tp_name] = {}
+        report["ground_truth_present"][tp_name] = False
+
+        # Check each modality
+        for mod in EXPECTED_MODALITIES:
+            mod_files = list(tp_dir.glob(f"*_{mod}.nii.gz"))
+            if not mod_files:
+                mod_files = list(tp_dir.glob(f"*_{mod.lower()}.nii.gz"))
+            report["modalities_complete"][tp_name][mod] = len(mod_files) > 0
+            if not mod_files:
+                report["missing_files"].append(f"{tp_name}/*_{mod}.nii.gz")
+
+        # Check ground truth
+        if has_ground_truth:
+            lesion_files = list(tp_dir.glob("*_lesion.nii.gz"))
+            report["ground_truth_present"][tp_name] = len(lesion_files) > 0
+            if not lesion_files and tp_name == report["timepoints"][0]:
+                report["warnings"].append(f"Missing ground truth in first timepoint: {tp_name}")
+
+    return report
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate MS Lesion Challenge directory structure."
+    )
+    parser.add_argument("--input", required=True, help="Path to MS Challenge directory")
+    parser.add_argument("--output", required=True, help="Output path for validation CSV")
+    parser.add_argument("--no-ground-truth", action="store_true",
+                        help="Skip ground truth validation (for test data)")
+    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 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, has_ground_truth=not args.no_ground_truth)
+        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", "timepoints", "modalities_complete", "ground_truth_present", "warnings"])
+        for r in results:
+            writer.writerow([
+                r["subject"],
+                len(r["timepoints"]),
+                str(r["modalities_complete"]),
+                str(r["ground_truth_present"]),
+                "; ".join(r["warnings"]),
+            ])
+
+    # Summary
+    total_timepoints = sum(len(r["timepoints"]) for r in results)
+    print(f"\nValidation Summary:")
+    print(f"  Subjects: {len(results)}")
+    print(f"  Total timepoints: {total_timepoints}")
+    print(f"  Output: {output_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,184 @@
+---
+name: nibabel-skill
+description: "Use this skill whenever NeuroClaw needs concrete nibabel operations for neuroimaging files: loading and validating NIfTI images, inspecting shapes and affine matrices, saving derived images, converting voxel coordinates to MNI/world coordinates, or reading FreeSurfer geometry and annotation files. Triggers include: 'nibabel', 'inspect NIfTI', 'read affine', 'save nifti', 'voxel to MNI', 'atlas coordinates', 'read FreeSurfer surface', 'read annot', or any request focused on low-level neuroimaging I/O rather than full preprocessing."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: tool
+dependencies: []
+---
+# Nibabel Skill
+
+## Overview
+
+`nibabel-skill` is the NeuroClaw tool skill for low-level neuroimaging file I/O and geometry handling.
+
+It is the right skill when the task is about reading or writing NIfTI data, checking image dimensions and affine matrices, extracting atlas-space coordinates, or interacting with FreeSurfer surface and annotation files.
+
+This skill is intentionally narrower than `nilearn-tool` and `brain-visualization`:
+- `nibabel-skill` focuses on file structures, affines, voxel/world coordinates, and surface geometry I/O
+- `nilearn-tool` focuses on signal processing, masking, ROI time series, and statistical image workflows
+- `brain-visualization` focuses on final figure generation and mesh export workflows
+
+The content is distilled from nibabel-centric patterns that appear repeatedly in `rs-fMRI-Pipeline-Tutorial/`, especially:
+- NIfTI discovery and validation in the multimodal pipeline
+- affine-based ROI center conversion in zALFF regional summaries
+- FreeSurfer geometry and annotation loading for colored surface export
+
+## Agent Reference Rule
+
+When the agent needs nibabel-based code, it should start from the curated snippets in `skills/nibabel-skill/scripts/` instead of copying tutorial files with hard-coded paths.
+
+Reference snippets available:
+- `scripts/nifti_inspection_reference.py` -> load NIfTI, inspect shape/dtype/affine, save a copied image
+- `scripts/atlas_coordinate_reference.py` -> compute atlas ROI centers and convert voxel coordinates to world coordinates
+- `scripts/freesurfer_io_reference.py` -> read FreeSurfer geometry/annotation and summarize mesh/color-table metadata
+
+## Quick Reference
+
+| Task | What it does | Typical input | Expected output |
+|------|--------------|---------------|-----------------|
+| NIfTI inspection | Loads an image and reports shape, dtype, affine, zooms | `.nii` / `.nii.gz` | metadata summary |
+| NIfTI save/export | Saves processed arrays back to NIfTI with an affine | array + affine | output image |
+| Atlas coordinate extraction | Converts ROI voxel centers to atlas/world coordinates | labeled atlas NIfTI | CSV / printed coordinates |
+| FreeSurfer surface I/O | Reads `.pial`, `.white`, `.annot` and summarizes geometry | surface + annot files | geometry summary |
+
+## Installation
+
+Install nibabel-related dependencies in the existing `neuroclaw` environment:
+
+```bash
+conda activate neuroclaw
+conda install -n neuroclaw -c conda-forge nibabel numpy pandas -y
+```
+
+Optional companion packages for downstream workflows:
+
+```bash
+conda install -n neuroclaw -c conda-forge nilearn scipy matplotlib -y
+```
+
+## Core Usage Patterns
+
+### 1. NIfTI Inspection and Validation
+
+Recommended when the user needs to verify whether a NIfTI file is 3D or 4D, whether the affine looks valid, or whether an image can be reused in later steps.
+
+Typical nibabel operations:
+- `nib.load(...)`
+- `img.shape`
+- `img.affine`
+- `img.get_fdata()`
+- `img.header.get_zooms()`
+- `nib.Nifti1Image(...)`
+- `nib.save(...)`
+
+Example command pattern:
+
+```bash
+python skills/nibabel-skill/scripts/nifti_inspection_reference.py \
+  --image path/to/image.nii.gz \
+  --copy-output outputs/image_copy.nii.gz
+```
+
+### 2. Atlas ROI Coordinate Extraction
+
+Recommended when the task is to convert ROI labels into approximate world or MNI coordinates.
+
+Typical nibabel operations:
+- load labeled atlas volumes with `nib.load(...)`
+- find ROI voxels with `numpy.argwhere(...)`
+- compute ROI centers with `numpy.median(...)`
+- convert voxel indices to world coordinates with `nib.affines.apply_affine(...)`
+
+Example command pattern:
+
+```bash
+python skills/nibabel-skill/scripts/atlas_coordinate_reference.py \
+  --atlas path/to/AAL3v1.nii \
+  --labels path/to/AAL3v1.nii.txt \
+  --output outputs/atlas_roi_centers.csv
+```
+
+### 3. FreeSurfer Geometry and Annotation I/O
+
+Recommended when the task is to inspect or reuse FreeSurfer surfaces and annotation color tables before later visualization/export steps.
+
+Typical nibabel operations:
+- `nibabel.freesurfer.read_geometry(...)`
+- `nibabel.freesurfer.read_annot(...)`
+
+Example command pattern:
+
+```bash
+python skills/nibabel-skill/scripts/freesurfer_io_reference.py \
+  --surf path/to/lh.pial \
+  --annot path/to/lh.aparc.annot
+```
+
+## Curated Reference Scripts
+
+### `scripts/nifti_inspection_reference.py`
+
+Purpose:
+- load NIfTI files safely
+- inspect dimensionality, dtype, zooms, and affine
+- optionally save a copy using the original affine and header
+
+Relevant tutorial sources:
+- `rs-fMRI-Pipeline-Tutorial/multimodal_brain_connectivity_pipeline.py`
+- `rs-fMRI-Pipeline-Tutorial/MNI152_zALFF_Brain_Region_Activation_Analysis.py`
+
+### `scripts/atlas_coordinate_reference.py`
+
+Purpose:
+- extract ROI ids from a labeled atlas
+- map ROI voxel centers into atlas/world coordinates
+- export a structured CSV table for downstream use
+
+Relevant tutorial sources:
+- `rs-fMRI-Pipeline-Tutorial/MNI152_zALFF_Brain_Region_Activation_Analysis.py`
+
+### `scripts/freesurfer_io_reference.py`
+
+Purpose:
+- inspect FreeSurfer mesh size and annotation coverage
+- summarize vertex counts, face counts, label ids, and available colors
+- serve as the low-level I/O basis for mesh export workflows
+
+Relevant tutorial sources:
+- `rs-fMRI-Pipeline-Tutorial/export_colored_ply_from_freesurfer.py`
+
+## Important Notes & Limitations
+
+- `nibabel-skill` is not a replacement for preprocessing tools such as FSL, fMRIPrep, or Nilearn workflows.
+- Affine correctness matters: voxel coordinates are meaningless without the right affine transform.
+- Atlas label files and atlas volumes may not align perfectly by naming convention; always validate label counts.
+- FreeSurfer `.annot` label ids are not always a direct 0..N index into user expectations; inspect the returned tables carefully.
+
+## When to Call This Skill
+
+- The agent needs to read or validate a NIfTI image before running downstream analysis.
+- The user asks for affine, shape, dtype, or voxel/world coordinate inspection.
+- The task involves extracting ROI centers from an atlas volume.
+- The task involves reading FreeSurfer surfaces or annotations before mesh export.
+
+## Complementary / Related Skills
+
+- `nilearn-tool` -> higher-level masking, ROI extraction, connectivity, GLM workflows
+- `brain-visualization` -> final connectome figures and PLY export workflows
+- `freesurfer-tool` -> full structural processing and recon-all workflows
+
+## Reference
+
+This skill is adapted from the nibabel-related code patterns in:
+- rs-fMRI-Pipeline-Tutorial: https://github.com/Karcen/rs-fMRI-Pipeline-Tutorial
+
+Curated reference snippets in this skill:
+- `skills/nibabel-skill/scripts/nifti_inspection_reference.py`
+- `skills/nibabel-skill/scripts/atlas_coordinate_reference.py`
+- `skills/nibabel-skill/scripts/freesurfer_io_reference.py`
+
+---
+Created At: 2026-04-14 00:23 HKT  
+Last Updated At: 2026-04-14 00:23 HKT  
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/nibabel-skill/scripts/atlas_coordinate_reference.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+
+
+def load_labels(label_path: Path) -> list[str]:
+    with label_path.open("r", encoding="utf-8", errors="ignore") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def get_roi_center(atlas_data: np.ndarray, affine: np.ndarray, roi_id: int) -> list[float]:
+    coords = np.argwhere(atlas_data == roi_id)
+    if len(coords) == 0:
+        return [0.0, 0.0, 0.0]
+    center = np.median(coords, axis=0)
+    xyz = nib.affines.apply_affine(affine, center)
+    return np.round(xyz, 2).tolist()
+
+
+def export_atlas_centers(atlas_path: Path, label_path: Path, output_path: Path) -> None:
+    atlas_img = nib.load(str(atlas_path))
+    atlas_data = atlas_img.get_fdata()
+    labels = load_labels(label_path)
+
+    roi_ids = sorted(int(value) for value in np.unique(atlas_data) if value > 0)
+    rows = []
+    for roi_id in roi_ids:
+        center = get_roi_center(atlas_data, atlas_img.affine, roi_id)
+        label_name = labels[roi_id - 1] if roi_id - 1 < len(labels) else f"ROI_{roi_id}"
+        rows.append(
+            {
+                "Region_ID": roi_id,
+                "Region_Name": label_name,
+                "MNI_X": center[0],
+                "MNI_Y": center[1],
+                "MNI_Z": center[2],
+            }
+        )
+
+    table = pd.DataFrame(rows)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    table.to_csv(output_path, index=False)
+    print(f"Saved atlas ROI centers to: {output_path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference script for atlas ROI center extraction with nibabel.")
+    parser.add_argument("--atlas", type=Path, required=True, help="Input atlas NIfTI with integer ROI labels.")
+    parser.add_argument("--labels", type=Path, required=True, help="Text file containing ROI labels.")
+    parser.add_argument("--output", type=Path, required=True, help="Output CSV for ROI centers.")
+    args = parser.parse_args()
+    export_atlas_centers(args.atlas, args.labels, args.output)
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nibabel-skill/scripts/freesurfer_io_reference.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel.freesurfer as fs
+import numpy as np
+
+
+def summarize_freesurfer_files(surf_path: Path, annot_path: Path) -> None:
+    coords, faces = fs.read_geometry(str(surf_path))
+    labels, color_table, names = fs.read_annot(str(annot_path))
+
+    unique_labels = np.unique(labels)
+    print(f"Surface: {surf_path}")
+    print(f"Vertices: {len(coords)}")
+    print(f"Faces: {len(faces)}")
+    print(f"Annotation: {annot_path}")
+    print(f"Unique annotation ids: {len(unique_labels)}")
+    print(f"Color table rows: {len(color_table)}")
+    print(f"Annotation names: {len(names)}")
+    print(f"Vertex coordinate sample: {coords[0].tolist() if len(coords) else []}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference script for FreeSurfer geometry and annotation I/O with nibabel.")
+    parser.add_argument("--surf", type=Path, required=True, help="FreeSurfer surface file such as lh.pial.")
+    parser.add_argument("--annot", type=Path, required=True, help="FreeSurfer annotation file such as lh.aparc.annot.")
+    args = parser.parse_args()
+    summarize_freesurfer_files(args.surf, args.annot)
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nibabel-skill/scripts/nifti_inspection_reference.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+
+
+def inspect_nifti(image_path: Path, copy_output: Path | None = None) -> None:
+    image = nib.load(str(image_path))
+    print(f"Path: {image_path}")
+    print(f"Shape: {image.shape}")
+    print(f"Data type: {image.get_data_dtype()}")
+    print(f"Zooms: {image.header.get_zooms()}")
+    print("Affine:")
+    print(image.affine)
+
+    if copy_output is not None:
+        data = image.get_fdata()
+        copied = nib.Nifti1Image(data, image.affine, image.header)
+        copy_output.parent.mkdir(parents=True, exist_ok=True)
+        nib.save(copied, str(copy_output))
+        print(f"Saved copy to: {copy_output}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference script for NIfTI inspection and save operations with nibabel.")
+    parser.add_argument("--image", type=Path, required=True, help="Input NIfTI image (.nii or .nii.gz).")
+    parser.add_argument("--copy-output", type=Path, default=None, help="Optional output path for saving an image copy.")
+    args = parser.parse_args()
+    inspect_nifti(args.image, args.copy_output)
+
+
+if __name__ == "__main__":
+    main()