@brainpilot/skills 0.0.6 → 0.0.7

package/skills/06_fMRI_Neuroimaging/nii2dcm/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: nii2dcm
+description: "Use this skill whenever the user wants to convert NIfTI files (.nii or .nii.gz) to DICOM format, create DICOM series from processed neuroimaging results, write segmentation/registration/analysis outputs back to DICOM for PACS compatibility or clinical viewer comparison, or transfer metadata from reference DICOM files. Triggers include: mentions of 'NIfTI to DICOM', 'nii to dcm', 'convert nii.gz to DICOM', 'dicomify segmentation', 'nii2dcm', 'bring results back to DICOM', 'create DICOM from NIfTI', 'nii to dicom series', or any request to take post-processed neuroimaging results (segmentation, registration, bias field correction, synthesis, etc.) and store/view them alongside original patient DICOM data. Also use when modality-specific metadata (especially MR, SVR) or preservation of patient/study information from a reference DICOM is needed. Do NOT use for the reverse conversion (DICOM to NIfTI), non-medical imaging file conversions, or any clinical diagnostic or treatment-related workflows."
+license: BSD 3-Clause (original nii2dcm license). See https://github.com/tomaroberts/nii2dcm/blob/main/LICENSE for complete terms.
+layer: base
+skill_type: tool
+dependencies:
+  - claw-shell
+---
+# NIfTI to DICOM conversion
+
+## Overview
+
+A NIfTI file (.nii/.nii.gz) is a compact format widely used in neuroimaging research, typically stripped of patient metadata.  
+DICOM is the clinical standard for medical images, including rich metadata and interoperability with PACS/hospital systems.
+
+This skill wraps `nii2dcm` (v0.1.6, May 2025) to convert NIfTI volumes into single-frame DICOM series (multi-slice 2D), primarily for MRI-derived data.  
+It supports modality-specific metadata (MR, SVR) and optional metadata transfer from a reference DICOM file.
+
+**Research use only** — not certified for clinical diagnosis, treatment, or patient care.
+
+## Quick Reference
+
+| Task                          | Approach / Command Flag                  |
+|-------------------------------|------------------------------------------|
+| Basic conversion (generic)    | `nii2dcm input.nii.gz output_dir/`       |
+| MRI multi-slice series        | `--dicom-type MR` or `-d MR`             |
+| SVR (3D swept volume recon)   | `--dicom-type SVR` or `-d SVR`           |
+| Copy patient/study metadata   | `--ref-dicom ref.dcm` or `-r ref.dcm`    |
+| Custom series description     | Add via wrapper or post-process          |
+| Verify output                 | Open in Horos, 3D Slicer, ITK-Snap       |
+
+## Installation
+
+### Via pip (recommended for NeuroClaw)
+```bash
+pip install nii2dcm>=0.1.6
+# or latest
+pip install git+https://github.com/tomaroberts/nii2dcm.git
+```
+
+### From source (for customization / debugging)
+```bash
+git clone https://github.com/tomaroberts/nii2dcm.git
+cd nii2dcm
+python -m venv venv
+source venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+pip install .
+nii2dcm -h   # Verify
+```
+
+Core dependencies (automatically installed):
+- highdicom >= 0.9.0
+- SimpleITK >= 2.2.0
+- pydicom
+- numpy
+
+Docker alternative (if preferred in containerized env):
+```bash
+docker pull ghcr.io/tomaroberts/nii2dcm:latest
+docker tag ghcr.io/tomaroberts/nii2dcm:latest nii2dcm
+docker run nii2dcm -v   # check version
+```
+
+## Usage Examples
+
+Core command pattern:
+```bash
+nii2dcm <input.nii[.gz]> <output_directory> [options]
+```
+
+### Create standard MRI DICOM series
+```bash
+nii2dcm processed_t1.nii.gz dicom_mr/ -d MR
+```
+
+### Create SVR (swept volume reconstruction) series
+```bash
+nii2dcm svr_recon.nii.gz dicom_svr/ -d SVR
+```
+
+### Generic conversion (no modality metadata)
+```bash
+nii2dcm seg_result.nii.gz dicom_generic/
+```
+
+### With reference DICOM (copy patient/study metadata)
+```bash
+nii2dcm hippocampus_seg.nii.gz dicom_seg/ -d MR -r original_T1_001.dcm
+```
+
+Transferred attributes (from DicomMRI class, see source):
+- PatientName, PatientID, PatientBirthDate, PatientSex
+- StudyInstanceUID, StudyDate, StudyTime, StudyDescription
+- SeriesInstanceUID, SeriesNumber, SeriesDescription, etc.
+(Full list: https://github.com/tomaroberts/nii2dcm/blob/main/nii2dcm/dcm.py#L236)
+
+### NeuroClaw recommended wrapper (simpler for agent calling)
+Use a thin wrapper script (to be provided in skill dir):
+```bash
+python nii2dcm_wrapper.py \
+  --input seg_postop.nii.gz \
+  --output-dir dicom_results/ \
+  --modality MR \
+  --ref-dcm ref_series/0001.dcm \
+  --series-desc "U-Net v3 Segmentation"
+```
+
+## Important Notes & Limitations
+
+- Supports only **3D single-volume → multi-slice 2D DICOM series** (common in structural MRI, segmentations)
+- **No 4D support** (fMRI, DWI, perfusion, DTI) — split volumes first if needed
+- Without `--dicom-type`, output is generic (lacks modality-specific tags)
+- Without `--ref-dicom`, patient/study info is anonymized/generic
+- Orientation, spacing, slice thickness read from NIfTI; verify alignment
+- **Always visually validate** output in DICOM viewer (Horos, 3D Slicer, ITK-Snap, MITK)
+- Project still in early stage — expect occasional bugs
+- **Research purpose only** — not a clinical tool
+
+## When to Call This Skill
+
+- Finished NIfTI-space processing (bias correction, registration, segmentation, synthesis, etc.)
+- Need to compare AI/model outputs visually with original clinical DICOM images
+- Want to store results in same format/framework as source study
+- Preparing outputs for PACS import, clinical collaboration, or archiving
+
+## Complementary / Related Skills
+- `dependency-planner`    → install dependencies
+- `claw-shell`            → safe execution of conversion commands
+
+## Reference
+
+Original: https://github.com/tomaroberts/nii2dcm (v0.1.6, May 2025)  
+Built on: highdicom (DICOM creation), SimpleITK (image I/O)  
+Inspired by: dcm2niix (reverse tool), SVRTK project
+
+Report issues or request extensions (e.g., CT support, 4D handling) in NeuroClaw repo.
+
+Created At: 2026-03-18 20:09 HKT
+Last Updated At: 2026-03-26 00:21 HKT  
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/nilearn-tool/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: nilearn-tool
+description: "Use this skill whenever any NeuroClaw fMRI modality skill needs to execute concrete Nilearn operations: ROI/atlas time-series extraction, confounds handling (fMRIPrep), seed-based connectivity maps, ROI-to-ROI connectivity matrices, and optional GLM/decoding utilities. This is the dedicated base/tool skill that contains Nilearn usage patterns and lightweight wrappers. Never called directly by the user."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: base
+skill_type: tool
+dependencies:
+  - claw-shell
+---
+# Nilearn Tool (Base/Tool Layer)
+
+## Overview
+`nilearn-tool` is the **NeuroClaw base/tool skill** that implements concrete **Nilearn** workflows for turning **preprocessed BOLD** into features (ROI time series, connectivity matrices, seed maps) and optional statistical modeling (GLM).
+
+It is **never called directly by the user**. It is delegated to by `fmri-skill` (or other interface/modality skills) and executed via `claw-shell`.
+
+**Research use only.**
+
+## Agent Reference Rule
+
+When the agent needs Nilearn-based implementation code, it should first consult the curated snippets in `skills/nilearn-tool/scripts/` instead of copying directly from long tutorial scripts with hard-coded paths.
+
+Reference snippets available:
+- `scripts/preprocess_bold_reference.py` -> dummy removal, smoothing, band-pass filtering, MNI resampling
+- `scripts/connectome_reference.py` -> atlas ROI extraction and ROI-to-ROI connectivity export
+- `scripts/zalff_summary_reference.py` -> MNI resampling, zALFF summary, atlas-level regional export
+- `scripts/task_glm_reference.py` -> first-level task GLM with design matrix and contrast maps
+- `scripts/second_level_glm_reference.py` -> group-level GLM from subject contrast maps
+- `scripts/rest_ica_reference.py` -> resting-state CanICA component extraction
+- `scripts/rest_dictlearning_reference.py` -> resting-state DictLearning component extraction
+- `scripts/svm_classifier_reference.py` -> ROI/tabular disease classification with SVM
+- `scripts/spacenet_classifier_reference.py` -> voxel-wise disease classification with SpaceNet
+- `scripts/kmeans_parcellation_reference.py` -> mask-based K-means brain parcellation
+- `scripts/hierarchical_parcellation_reference.py` -> mask-based hierarchical brain parcellation
+- `scripts/denoise_timeseries_reference.py` -> confound regression and detrending with `clean_img`
+
+---
+
+## Scope (What this tool does / does not do)
+
+### ✅ This tool does
+- Load BOLD NIfTI and (optional) brain mask.
+- Load fMRIPrep confounds TSV and apply common denoising regressors.
+- Extract ROI time series from an atlas/parcellation.
+- Compute ROI-to-ROI functional connectivity matrices.
+- Compute seed-to-voxel connectivity maps.
+- (Optional) Run first-/second-level GLM when events/maps are provided.
+
+### ❌ This tool does NOT do
+- Raw fMRI preprocessing (slice timing, motion correction, susceptibility distortion correction, eddy/topup, etc.).
+  Those belong to `fmriprep-tool`, `hcppipeline-tool`, `fsl-tool`.
+
+---
+
+## Core Outputs (Typical)
+- `roi_timeseries.csv` (T × R)
+- `connectome.npy` / `connectome.csv` (R × R)
+- `seed_zmap.nii.gz`
+- (Optional) `first_level_zmap.nii.gz`, `second_level_zmap.nii.gz`
+- Optional figures: connectome matrix PNG, connectome graph PNG, stat map PNG
+
+---
+
+## Minimal Nilearn Usage Patterns (Short Snippets)
+
+### 1) fMRIPrep confounds (recommended)
+```python
+from nilearn.interfaces.fmriprep import load_confounds
+confounds, sample_mask = load_confounds(confounds_tsv, strategy=["motion", "wm_csf"])
+```
+
+### 2) ROI time series (atlas/parcellation)
+```python
+from nilearn.maskers import NiftiLabelsMasker
+masker = NiftiLabelsMasker(labels_img=atlas_img, t_r=tr, standardize=True, detrend=True)
+roi_ts = masker.fit_transform(bold_img, confounds=confounds, sample_mask=sample_mask)  # (T, R)
+```
+
+### 3) ROI-to-ROI connectivity
+```python
+from nilearn.connectome import ConnectivityMeasure
+conn = ConnectivityMeasure(kind="correlation").fit_transform([roi_ts])[0]  # (R, R)
+```
+
+### 4) Seed-to-voxel connectivity (concept)
+- Use `NiftiSpheresMasker` for seed TS, `NiftiMasker` for voxel TS, then correlate and Fisher-z.
+
+## Curated Reference Snippets
+
+These scripts are distilled from `rs-fMRI-Pipeline-Tutorial/` and should be the preferred starting point for new code in this skill:
+
+### `scripts/preprocess_bold_reference.py`
+- Covers the Nilearn-centric part of resting-state preprocessing shown in `multimodal_brain_connectivity_pipeline.py`
+- Includes dummy-scan removal, spatial smoothing, temporal band-pass filtering, and MNI152 resampling
+
+Example:
+```bash
+python skills/nilearn-tool/scripts/preprocess_bold_reference.py \
+  --bold path/to/rest_bold.nii.gz \
+  --output fmri_output/sub-001/nilearn/preprocessed_bold_mni.nii.gz
+```
+
+### `scripts/connectome_reference.py`
+- Extracts atlas ROI time series with `NiftiLabelsMasker`
+- Computes ROI-to-ROI connectivity with `ConnectivityMeasure`
+- Exports `roi_timeseries.csv`, `connectome.npy`, and `connectome.csv`
+
+Example:
+```bash
+python skills/nilearn-tool/scripts/connectome_reference.py \
+  --bold path/to/preprocessed_bold_mni.nii.gz \
+  --atlas path/to/AAL3v1.nii \
+  --labels path/to/AAL3v1.nii.txt \
+  --output-dir fmri_output/sub-001/nilearn/connectome
+```
+
+### `scripts/zalff_summary_reference.py`
+- Adapts the regional zALFF summarization logic from `MNI152_zALFF_Brain_Region_Activation_Analysis.py`
+- Uses Nilearn resampling, cleaning, and `NiftiLabelsMasker` for atlas-level reporting
+
+Example:
+```bash
+python skills/nilearn-tool/scripts/zalff_summary_reference.py \
+  --bold path/to/rest_bold.nii.gz \
+  --atlas path/to/AAL3v1.nii \
+  --labels path/to/AAL3v1.nii.txt \
+  --mask path/to/mni_mask.nii.gz \
+  --output-dir fmri_output/sub-001/nilearn/zalff
+```
+
+### Additional model-routing snippets
+- `scripts/task_glm_reference.py` -> first-level task GLM
+- `scripts/second_level_glm_reference.py` -> second-level / group GLM
+- `scripts/rest_ica_reference.py` -> resting-state ICA decomposition
+- `scripts/rest_dictlearning_reference.py` -> resting-state DictLearning decomposition
+- `scripts/svm_classifier_reference.py` -> tabular / ROI SVM classifier
+- `scripts/spacenet_classifier_reference.py` -> voxel-wise SpaceNet classifier
+- `scripts/kmeans_parcellation_reference.py` -> K-means parcellation from masked image features
+- `scripts/hierarchical_parcellation_reference.py` -> Hierarchical parcellation from masked image features
+- `scripts/denoise_timeseries_reference.py` -> confound-aware detrending and time-series cleaning
+
+---
+
+## Wrapper Entry (Recommended)
+This tool should expose a **small CLI wrapper** (implementation kept in a separate file, not embedded here):
+- File: `skills/nilearn-tool/nilearn_pipeline.py`
+- Subcommands (recommended):
+  - `roi-ts` → extract ROI time series
+  - `connectome` → compute connectivity matrix from ROI TS
+  - `seed-corr` → seed connectivity z-map
+  - `first-glm` / `second-glm` (optional)
+
+**All execution must be routed through `claw-shell`.**
+
+Example calls:
+```bash
+conda run -n neuroclaw-nilearn python skills/nilearn-tool/nilearn_pipeline.py roi-ts \
+  --bold <preproc_bold.nii.gz> --confounds <confounds.tsv> --tr 2.0 --atlas schaefer_2018_200_7 \
+  --outdir fmri_output/sub-001/nilearn/roi_ts
+
+conda run -n neuroclaw-nilearn python skills/nilearn-tool/nilearn_pipeline.py connectome \
+  --roi-timeseries fmri_output/sub-001/nilearn/roi_ts/roi_timeseries.csv --kind correlation \
+  --outdir fmri_output/sub-001/nilearn/connectome
+```
+
+---
+
+## Installation (Handled by `dependency-planner`)
+Recommended isolated environment:
+```bash
+conda create -n neuroclaw-nilearn python=3.11 -y
+conda install -n neuroclaw-nilearn -c conda-forge nilearn nibabel numpy scipy pandas scikit-learn matplotlib -y
+```
+
+---
+
+## Safety / Execution Rules (NeuroClaw)
+- No direct `subprocess.run()` for long operations in this skill.
+- All shell commands go through `claw-shell`.
+- Always produce outputs under `fmri_output/.../nilearn/...` with deterministic filenames.
+
+---
+
+## Complementary / Related Skills
+- `dependency-planner` + `conda-env-manager` → install/manage `neuroclaw-nilearn`
+- `claw-shell` → mandatory execution layer
+
+---
+
+## Reference
+- Nilearn documentation: https://nilearn.github.io/
+- fMRIPrep confounds interface: Nilearn `nilearn.interfaces.fmriprep`
+- Curated code snippets in this skill:
+  - `skills/nilearn-tool/scripts/preprocess_bold_reference.py`
+  - `skills/nilearn-tool/scripts/connectome_reference.py`
+  - `skills/nilearn-tool/scripts/zalff_summary_reference.py`
+  - `skills/nilearn-tool/scripts/task_glm_reference.py`
+  - `skills/nilearn-tool/scripts/second_level_glm_reference.py`
+  - `skills/nilearn-tool/scripts/rest_ica_reference.py`
+  - `skills/nilearn-tool/scripts/rest_dictlearning_reference.py`
+  - `skills/nilearn-tool/scripts/svm_classifier_reference.py`
+  - `skills/nilearn-tool/scripts/spacenet_classifier_reference.py`
+  - `skills/nilearn-tool/scripts/kmeans_parcellation_reference.py`
+  - `skills/nilearn-tool/scripts/hierarchical_parcellation_reference.py`
+  - `skills/nilearn-tool/scripts/denoise_timeseries_reference.py`
+
+## Post-Execution Verification (Harness Integration)
+
+After Nilearn processing completes, this skill **automatically invokes harness-core's VerificationRunner** to validate output integrity:
+
+**Integrated verification checks**:
+
+```python
+from skills.harness_core import VerificationRunner, AuditLogger
+
+verifier = VerificationRunner(task_type="nilearn_processing")
+
+# 1. ROI time series shape and completeness
+verifier.add_check("roi_timeseries",
+    checker=lambda: verify_roi_timeseries(output_dir),
+    severity="error"
+)
+
+# 2. Confounds loading and application
+verifier.add_check("confounds_handling",
+    checker=lambda: verify_confounds_applied(output_dir),
+    severity="warning"
+)
+
+# 3. Connectivity matrix dimensionality (N_ROI × N_ROI)
+verifier.add_check("connectivity_shape",
+    checker=lambda: verify_connectome_shape(output_dir),
+    severity="error"
+)
+
+# 4. Correlation bounds (-1 to +1)
+verifier.add_check("correlation_bounds",
+    checker=lambda: verify_correlation_bounds(output_dir),
+    severity="warning"
+)
+
+# 5. Data integrity (NaN/Inf checks)
+verifier.add_check("data_integrity",
+    checker=lambda: verify_no_nan_inf(output_dir),
+    severity="error"
+)
+
+report = verifier.run(output_dir)
+
+# Log verification results
+logger = AuditLogger(log_file=f"{output_dir}/nilearn_verification.jsonl")
+logger.log_validation(
+    task_name="nilearn_processing",
+    checks_passed=len([r for r in report.results if r.passed]),
+    total_checks=len(report.results),
+    output_path=output_dir
+)
+```
+
+**Output**: `fmri_output/nilearn_verification.jsonl` (structured audit log with JSONL format)
+
+---
+
+Created At: 2026-03-26 00:54 HKT
+Last Updated At: 2026-04-14 00:26 HKT
+Author: chengwang96

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/connectome_reference.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+from nilearn.connectome import ConnectivityMeasure
+from nilearn.maskers import NiftiLabelsMasker
+
+
+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 export_connectome(
+    bold_path: Path,
+    atlas_path: Path,
+    output_dir: Path,
+    tr: float,
+    label_path: Path | None = None,
+) -> None:
+    bold_img = nib.load(str(bold_path))
+    masker = NiftiLabelsMasker(labels_img=str(atlas_path), t_r=tr, standardize=True, detrend=True)
+    roi_time_series = masker.fit_transform(bold_img)
+
+    connectome = ConnectivityMeasure(kind="correlation").fit_transform([roi_time_series])[0]
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    np.save(output_dir / "connectome.npy", connectome)
+    pd.DataFrame(roi_time_series).to_csv(output_dir / "roi_timeseries.csv", index=False)
+
+    if label_path is not None:
+        labels = load_labels(label_path)
+        count = min(len(labels), connectome.shape[0])
+        pd.DataFrame(connectome[:count, :count], index=labels[:count], columns=labels[:count]).to_csv(
+            output_dir / "connectome.csv"
+        )
+    else:
+        pd.DataFrame(connectome).to_csv(output_dir / "connectome.csv", index=False)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn snippet for ROI extraction and connectome computation.")
+    parser.add_argument("--bold", type=Path, required=True, help="Input preprocessed BOLD NIfTI.")
+    parser.add_argument("--atlas", type=Path, required=True, help="Atlas NIfTI for ROI extraction.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for ROI and connectome outputs.")
+    parser.add_argument("--tr", type=float, default=1.0, help="Repetition time in seconds.")
+    parser.add_argument("--labels", type=Path, default=None, help="Optional atlas label text file.")
+    args = parser.parse_args()
+
+    export_connectome(
+        bold_path=args.bold,
+        atlas_path=args.atlas,
+        output_dir=args.output_dir,
+        tr=args.tr,
+        label_path=args.labels,
+    )
+    print(f"Saved connectome outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/denoise_timeseries_reference.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import pandas as pd
+from nilearn import image
+
+
+def run_denoising(
+    bold_path: Path,
+    output_dir: Path,
+    tr: float,
+    confounds_path: Path | None = None,
+    mask_path: Path | None = None,
+    detrend: bool = False,
+    standardize: bool = True,
+) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    confounds = pd.read_csv(confounds_path, sep=None, engine="python") if confounds_path is not None else None
+    cleaned = image.clean_img(
+        str(bold_path),
+        confounds=confounds,
+        detrend=detrend,
+        standardize=standardize,
+        mask_img=str(mask_path) if mask_path is not None else None,
+        t_r=tr,
+    )
+    nib.save(cleaned, str(output_dir / "cleaned_bold.nii.gz"))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference Nilearn snippet for confound regression and detrending.")
+    parser.add_argument("--bold", type=Path, required=True, help="Input preprocessed BOLD image.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for cleaned outputs.")
+    parser.add_argument("--tr", type=float, required=True, help="Repetition time in seconds.")
+    parser.add_argument("--confounds", type=Path, default=None, help="Optional confounds TSV/CSV.")
+    parser.add_argument("--mask", type=Path, default=None, help="Optional mask image.")
+    parser.add_argument("--detrend", action="store_true", help="Enable temporal detrending.")
+    parser.add_argument("--no-standardize", action="store_true", help="Disable standardization.")
+    args = parser.parse_args()
+
+    run_denoising(
+        bold_path=args.bold,
+        output_dir=args.output_dir,
+        tr=args.tr,
+        confounds_path=args.confounds,
+        mask_path=args.mask,
+        detrend=args.detrend,
+        standardize=not args.no_standardize,
+    )
+    print(f"Saved cleaned outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/hierarchical_parcellation_reference.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+from nilearn.maskers import NiftiMasker
+from sklearn.cluster import AgglomerativeClustering
+
+
+def load_image_list(list_path: Path) -> list[str]:
+    with list_path.open("r", encoding="utf-8") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def build_feature_matrix(images: list[str], masker: NiftiMasker) -> np.ndarray:
+    subject_vectors = [masker.fit_transform(image_path) for image_path in images]
+    stacked = np.vstack(subject_vectors)
+    return stacked.reshape(len(images), -1, stacked.shape[-1]).mean(axis=0)
+
+
+def run_hierarchical(input_list: Path, output_dir: Path, n_clusters: int, mask_path: Path) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    images = load_image_list(input_list)
+
+    masker = NiftiMasker(mask_img=str(mask_path), standardize=True)
+    features = build_feature_matrix(images, masker)
+    model = AgglomerativeClustering(n_clusters=n_clusters, linkage="ward")
+    labels = model.fit_predict(features)
+
+    label_img = masker.inverse_transform(labels[:, None].astype(float))
+    nib.save(label_img, str(output_dir / "parcel_labels.nii.gz"))
+    pd.DataFrame({"cluster": np.arange(n_clusters), "size": np.bincount(labels, minlength=n_clusters)}).to_csv(
+        output_dir / "cluster_summary.csv", index=False
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference snippet for hierarchical neuroimaging parcellation.")
+    parser.add_argument("--input-list", type=Path, required=True, help="Text file listing aligned images.")
+    parser.add_argument("--mask", type=Path, required=True, help="Mask image defining spatial units.")
+    parser.add_argument("--n-clusters", type=int, required=True, help="Number of clusters / parcels.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for parcellation outputs.")
+    args = parser.parse_args()
+
+    run_hierarchical(args.input_list, args.output_dir, args.n_clusters, args.mask)
+    print(f"Saved hierarchical parcellation outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/06_fMRI_Neuroimaging/nilearn-tool/scripts/kmeans_parcellation_reference.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+import pandas as pd
+from nilearn.maskers import NiftiMasker
+from sklearn.cluster import KMeans
+
+
+def load_image_list(list_path: Path) -> list[str]:
+    with list_path.open("r", encoding="utf-8") as handle:
+        return [line.strip() for line in handle if line.strip()]
+
+
+def build_feature_matrix(images: list[str], masker: NiftiMasker) -> np.ndarray:
+    subject_vectors = [masker.fit_transform(image_path) for image_path in images]
+    stacked = np.vstack(subject_vectors)
+    return stacked.reshape(len(images), -1, stacked.shape[-1]).mean(axis=0)
+
+
+def run_kmeans(input_list: Path, output_dir: Path, n_clusters: int, mask_path: Path) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    images = load_image_list(input_list)
+
+    masker = NiftiMasker(mask_img=str(mask_path), standardize=True)
+    features = build_feature_matrix(images, masker)
+    model = KMeans(n_clusters=n_clusters, random_state=0, n_init=10)
+    labels = model.fit_predict(features)
+
+    label_img = masker.inverse_transform(labels[:, None].astype(float))
+    nib.save(label_img, str(output_dir / "parcel_labels.nii.gz"))
+    pd.DataFrame({"cluster": np.arange(n_clusters), "size": np.bincount(labels, minlength=n_clusters)}).to_csv(
+        output_dir / "cluster_summary.csv", index=False
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference snippet for K-means-based neuroimaging parcellation.")
+    parser.add_argument("--input-list", type=Path, required=True, help="Text file listing aligned images.")
+    parser.add_argument("--mask", type=Path, required=True, help="Mask image defining spatial units.")
+    parser.add_argument("--n-clusters", type=int, required=True, help="Number of clusters / parcels.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for parcellation outputs.")
+    args = parser.parse_args()
+
+    run_kmeans(args.input_list, args.output_dir, args.n_clusters, args.mask)
+    print(f"Saved K-means parcellation outputs to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()