@brainpilot/skills 0.0.6 → 0.0.7

package/skills/07_Computational_Modeling/svm/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: svm
+description: "Use this model doc whenever the user wants to perform disease classification with SVM. This is a non-deep-learning supervised route focused on neuroimaging-based case-control prediction from ROI-wise or tabular features."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: model
+dependencies:
+  - fmri-skill
+  - smri-skill
+  - nilearn-tool
+  - run_models
+---
+# SVM Model Doc
+
+## Overview
+SVM is a classical non-deep-learning method for neuroimaging-based disease classification.
+
+- Model family: non-deep-learning supervised classification method
+- Typical objectives:
+  - classify patient vs control groups from neuroimaging features
+  - build discriminative models from ROI features or tabular summaries
+  - export predictive scores and evaluation metrics
+- Primary input: preprocessed fMRI / sMRI derived features, labels, optional covariates
+- Primary output: class predictions, decision scores, cross-validation metrics
+
+In NeuroClaw, this document is model-level guidance for SVM-based disease classification workflows rather than deep learning phenotype prediction.
+
+Upstream preparation should usually be delegated to:
+- `fmri-skill` for fMRI preprocessing and ROI / voxel feature preparation
+- `smri-skill` for structural feature extraction when disease classification uses sMRI
+- `nilearn-tool` for concrete SVM fitting on prepared feature tables
+
+**Research use only.**
+
+---
+
+## Quick Start
+
+### 1) Prepare disease classification inputs
+Expected inputs:
+- subject-level labels such as patient / control
+- preprocessed imaging features
+- optional covariates such as age, sex, site
+- optional train / validation / test split definition
+
+If features are not ready, delegate preprocessing to `fmri-skill` or `smri-skill` first.
+
+### 2) SVM route
+Representative operations:
+- prepare ROI-wise or tabular neuroimaging features
+- standardize features within the training fold
+- fit linear or kernel SVM for disease classification
+- export predictions, decision scores, and performance metrics
+
+Example execution route:
+```bash
+# delegated through claw-shell after features are prepared
+python skills/nilearn-tool/scripts/svm_classifier_reference.py \
+  --features path/to/features.csv \
+  --labels path/to/labels.csv \
+  --target diagnosis \
+  --cv 5 \
+  --output-dir run_models_output/svm
+```
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- subject-level labels for disease classification
+- feature table or ROI summary matrix
+
+### Optional inputs
+- confounds or covariates table
+- train / validation / test split file
+- hyperparameter settings such as kernel, C, or number of CV folds
+
+### Produced outputs
+- predicted labels and decision scores
+- cross-validation metrics such as accuracy, AUC, sensitivity, specificity
+- fitted model artifact or coefficient table
+
+---
+
+## Recommended Delegation
+
+- imaging preprocessing and feature preparation -> `fmri-skill` and/or `smri-skill`
+- concrete implementation of SVM -> `nilearn-tool`
+- shell execution and logging -> `claw-shell`
+
+No execution before explicit plan confirmation.
+
+---
+
+## When to Use SVM
+
+- The user wants classical disease classification instead of a deep learning model.
+- The dataset size is moderate and model interpretability matters.
+- ROI-level features are already prepared and SVM is sufficient.
+- The task is case-control prediction, diagnosis support, or cross-validated disease discrimination.
+
+---
+
+## Limitations and Notes
+
+- SVM performance depends strongly on feature engineering, scaling, and leakage-free cross-validation.
+- Site effects and confounds can dominate disease classification if not controlled properly.
+- Small sample sizes can lead to optimistic estimates unless split strategy is rigorously managed.
+
+---
+
+## Reference
+
+- Cortes C, Vapnik V. Support-vector networks.
+- Nilearn decoding documentation: https://nilearn.github.io/stable/decoding/index.html
+
+Created At: 2026-04-14 00:34 HKT
+Last Updated At: 2026-04-14 00:45 HKT
+Author: chengwang96

package/skills/08_Computational_Neuroscience/brain_gnn/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: braingnn
+description: "Use this model doc whenever the user wants to run BrainGNN for fMRI phenotype prediction, including graph construction, training, and evaluation. This document focuses on model-level usage and delegates upstream preprocessing to fmri-skill (and optionally hcpya-skill for HCP data)."
+license: MIT License (NeuroClaw custom skill - freely modifiable within the project)
+layer: base
+skill_type: model
+dependencies:
+  - fmri-skill
+  - run_models
+---
+# BrainGNN Model Doc
+
+## Overview
+BrainGNN is an interpretable graph neural network for fMRI analysis and phenotype prediction.
+
+- Paper: Li et al., 2020, BrainGNN
+- Official code: https://github.com/xxlya/BrainGNN_Pytorch/tree/main
+- Primary input: ROI-level fMRI data (timeseries/connectivity)
+- Primary output: phenotype prediction (classification/regression, task-dependent)
+
+In NeuroClaw, this document is model-level guidance. Upstream data preparation should be delegated to:
+- `fmri-skill` for fMRI preprocessing and ROI extraction
+- `hcpya-skill` when HCP Young Adult dataset download/orchestration is needed
+
+**Research use only.**
+
+---
+
+## Quick Start (From git clone)
+
+### 1) Clone repository
+```bash
+git clone https://github.com/xxlya/BrainGNN_Pytorch.git
+cd BrainGNN_Pytorch
+```
+
+### 2) Create environment and install dependencies
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+If using GPU, install version-matched PyTorch/PyG builds first, then install remaining requirements.
+
+### 3) Prepare data (ROI first)
+Use `fmri-skill` to prepare ROI timeseries and metadata, then arrange files under:
+- `data/{dataset_name}-rest.csv`
+- `data/{dataset_name}_roi/`
+
+### 4) Run 3-phase pipeline
+```bash
+# Phase 1: build connectivity matrices
+python 01-fetch_data.py --atlas aal3 --dataset_name adhd200 --dataset_dir data
+
+# Phase 2: convert to graph samples
+python 02-process_data.py --atlas aal3 --dataset_name adhd200 --dataset_dir data --nclass 2 --score DX
+
+# Phase 3: train/evaluate BrainGNN
+CUDA_VISIBLE_DEVICES=0 python 03-main.py \
+  --atlas aal3 --dataset_name adhd200 --dataset_dir data \
+  --indim 166 --nroi 166 --nclass 2 --fold 0
+```
+
+---
+
+## Pipeline Definition
+
+### Phase 1: Connectivity Generation (`01-fetch_data.py`)
+Purpose: convert ROI timeseries to connectivity features.
+
+Outputs:
+- `data/{dataset_name}_roi/braingnn_{atlas}/*.mat`
+- `data/{dataset_name}_roi/braingnn_{atlas}/valid_subject_list.pkl`
+
+Key args:
+- `--atlas`: `aal3`, `dk`, `cc200`, `ho`
+- `--dataset_name`: `adhd200`, `cobre`, `UCLA`, `hcp-d`, `hcp-ep`, `ABCD`
+- `--dataset_dir`: root data dir, default `data`
+
+### Phase 2: Graph Construction (`02-process_data.py`)
+Purpose: convert connectivity matrices into per-subject graph files.
+
+Outputs:
+- `data/{dataset_name}_roi/braingnn_{atlas}/raw/{subject_id}.h5`
+
+Common args:
+- `--nclass`: class count
+- `--score`: label key (`DX`, `Gender`, `Age`)
+- `--seed`: random seed
+
+### Phase 3: Training and Evaluation (`03-main.py`)
+Purpose: train BrainGNN with fold-wise evaluation and checkpointing.
+
+Outputs:
+- `model/{fold}.pth`
+- `model/log/{fold}/` (TensorBoard)
+
+Core model options:
+- `--indim`, `--nroi`: must match atlas ROI count
+- `--nclass`: output classes
+- `--fold`: CV fold index
+- `--n_epochs`, `--batchSize`, `--lr`, `--weightdecay`
+
+---
+
+## Input / Output Contract
+
+### Required inputs
+- ROI timeseries per subject
+- Subject metadata CSV with labels
+- Dataset name and atlas selection
+
+### Produced outputs
+- Connectivity matrices and graph files
+- Trained checkpoint(s)
+- Evaluation logs and metrics
+
+---
+
+## Atlas and Dimension Mapping
+
+| Atlas | Typical ROI count | Required flags |
+|---|---:|---|
+| `aal3` | 166 | `--indim 166 --nroi 166` |
+| `cc200` | 200 | `--indim 200 --nroi 200` |
+| `dk` | atlas-dependent | set both flags to actual ROI count |
+| `ho` | atlas-dependent | set both flags to actual ROI count |
+
+If `--indim` or `--nroi` does not match the real ROI count, training will fail.
+
+---
+
+## Recommended Directory Layout
+
+```text
+BrainGNN_Pytorch/
+  data/
+    {dataset_name}-rest.csv
+    {dataset_name}_roi/
+      braingnn_{atlas}/
+        *.mat
+        valid_subject_list.pkl
+        raw/*.h5
+  model/
+    {fold}.pth
+    log/{fold}/
+```
+
+---
+
+## NeuroClaw Delegation Rules
+
+- ROI generation and preprocessing: delegate to `fmri-skill`
+- HCP download/orchestration (if needed): delegate to `hcpya-skill` (or `hcpa-skill` / `hcpd-skill` / `hcpep-skill` for other HCP variants)
+- Dependency checks: `dependency-planner` + `conda-env-manager`
+- Execution routing: `claw-shell`
+
+No execution before explicit plan confirmation.
+
+---
+
+## Limitations and Notes
+
+- This workflow assumes ROI data already exists before Phase 1.
+- GPU is strongly recommended for training speed.
+- Cross-validation is controlled by running Phase 3 repeatedly with different `--fold` values.
+- TensorBoard command:
+```bash
+tensorboard --logdir ./model/log/
+```
+
+---
+
+## Reference
+
+- Li X, Zhou Y, Dvornek N, Zhang M, Gao S, Zhuang J, Scheinost D, Staib L, Ventola P, Duncan J. 2020. BrainGNN.
+- Official repository: https://github.com/xxlya/BrainGNN_Pytorch/tree/main
+- PyG installation notes: https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html
+
+Created At: 2026-03-28 19:53 HKT
+Last Updated At: 2026-03-28 19:53 HKT
+Author: chengwang96

package/skills/08_Computational_Neuroscience/dipy-tool/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: dipy-tool
+description: "Use this skill whenever any NeuroClaw diffusion MRI / DWI modality skill needs to execute concrete DIPY operations: load DWI (NIfTI+bvals+bvecs), optional masking, DTI fitting, compute FA/MD/AD/RD, and extract ROI statistics. This is the dedicated base/tool skill that contains all specific DIPY code and usage patterns. 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
+---
+# DIPY Tool (Base/Tool Layer)
+
+## Overview
+`dipy-tool` is the **NeuroClaw base/tool skill** that provides the concrete **DIPY** implementation for diffusion MRI (DWI/DTI) processing and feature extraction.
+
+It is **never called directly by the user**. It is delegated to by a diffusion modality-layer skill (e.g., future `dwi-skill` / `dmri-skill`) and executed via `claw-shell` for safety, logging, and long-running stability.
+
+This skill provides:
+- Robust loading of **DWI NIfTI + bvals + bvecs** with sanity checks.
+- Brain mask generation (`median_otsu`) or use of a provided mask.
+- **DTI fitting** (optionally selecting a b-value range) and metric export:
+  - **FA / MD / AD / RD** as NIfTI maps
+- **ROI / atlas statistics** extraction (CSV summaries).
+
+**Research use only** — not for clinical diagnosis.
+
+## Agent Reference Rule
+
+When the agent needs DIPY-based implementation code, it should first consult the curated snippets in `skills/dipy-tool/scripts/` instead of copying the large embedded wrapper or unrelated tutorial files with hard-coded paths.
+
+Reference snippets available:
+- `scripts/load_and_mask_reference.py` -> DWI + gradients loading, b0 discovery, `median_otsu` brain masking
+- `scripts/dti_metrics_reference.py` -> tensor fitting and FA/MD/AD/RD export
+- `scripts/roi_stats_reference.py` -> atlas-based summary statistics on tensor metrics
+
+---
+
+## Quick Reference (Core Tasks)
+
+| Task | What it does | Output |
+|---|---|---|
+| Load DWI + gradients | Validates shapes, loads NIfTI+bvals+bvecs | in-memory arrays |
+| Brain mask | Auto mask (median_otsu) or use external | `brain_mask.nii.gz` |
+| DTI fit | TensorModel fit on selected volumes | tensor fit object |
+| Export tensor metrics | Compute & save FA/MD/AD/RD | `FA.nii.gz`, `MD.nii.gz`, `AD.nii.gz`, `RD.nii.gz` |
+| ROI stats | Per-label summary (mean/median/std/p05/p95) | `roi_stats_FA.csv`, etc. |
+
+---
+
+## Curated Reference Scripts
+
+These scripts are aligned with NeuroClaw's DWI handling pattern and with the modality / dependency expectations documented in `rs-fMRI-Pipeline-Tutorial/`:
+- the tutorial explicitly includes DTI/DWI as a supported modality
+- the tutorial installs `dipy` as a core dependency
+- the tutorial's multimodal structure motivates deterministic outputs and atlas-based summaries
+
+### `scripts/load_and_mask_reference.py`
+- Loads DWI NIfTI + bvals + bvecs with shape checks
+- Finds b0 volumes and builds a brain mask with `median_otsu`
+- Exports `brain_mask.nii.gz`, `mean_b0.nii.gz`, and `dwi_summary.txt`
+
+Example:
+```bash
+python skills/dipy-tool/scripts/load_and_mask_reference.py \
+    --dwi path/to/sub-001_dwi.nii.gz \
+    --bval path/to/sub-001_dwi.bval \
+    --bvec path/to/sub-001_dwi.bvec \
+    --output-dir dwi_output/sub-001/dipy/load_mask
+```
+
+### `scripts/dti_metrics_reference.py`
+- Filters gradients for tensor fitting
+- Fits a tensor model with DIPY
+- Exports `FA.nii.gz`, `MD.nii.gz`, `AD.nii.gz`, and `RD.nii.gz`
+
+Example:
+```bash
+python skills/dipy-tool/scripts/dti_metrics_reference.py \
+    --dwi path/to/sub-001_dwi.nii.gz \
+    --bval path/to/sub-001_dwi.bval \
+    --bvec path/to/sub-001_dwi.bvec \
+    --mask dwi_output/sub-001/dipy/load_mask/brain_mask.nii.gz \
+    --output-dir dwi_output/sub-001/dipy/metrics
+```
+
+### `scripts/roi_stats_reference.py`
+- Computes atlas-level statistics from tensor metrics
+- Supports optional label names for structured CSV outputs
+- Intended for FA/MD/AD/RD summaries after tensor fitting
+
+Example:
+```bash
+python skills/dipy-tool/scripts/roi_stats_reference.py \
+    --metric dwi_output/sub-001/dipy/metrics/FA.nii.gz \
+    --roi path/to/JHU_labels_in_dwi_space.nii.gz \
+    --output dwi_output/sub-001/dipy/roi_stats_FA.csv
+```
+
+---
+
+## Installation (Handled by `dependency-planner`)
+This tool is installed automatically when required.
+
+Recommended isolated environment:
+```bash
+conda create -n neuroclaw-dipy python=3.11 -y
+conda activate neuroclaw-dipy
+conda install -c conda-forge dipy nibabel numpy scipy scikit-image pandas -y
+# Optional:
+conda install -c conda-forge matplotlib -y
+```
+
+**Recommended execution pattern (avoids shell activation pitfalls):**
+- Use `conda run -n neuroclaw-dipy ...` routed through `claw-shell`.
+
+---
+
+## NeuroClaw recommended wrapper
+
+If a single entry point is still needed later, it should be assembled from the curated snippets in `skills/dipy-tool/scripts/` rather than keeping a long monolithic example embedded in this document.
+
+Recommended composition:
+- `load_and_mask_reference.py` for DWI sanity checks and mask creation
+- `dti_metrics_reference.py` for tensor fitting and FA/MD/AD/RD export
+- `roi_stats_reference.py` for atlas-based feature summarization
+
+All real runs must still be delegated to `claw-shell`.
+
+---
+
+## Example execution (must be routed via `claw-shell`)
+```bash
+conda run -n neuroclaw-dipy python skills/dipy-tool/dipy_pipeline.py \
+  --dwi /data/sub-001_dwi.nii.gz \
+  --bval /data/sub-001_dwi.bval \
+  --bvec /data/sub-001_dwi.bvec \
+  --outdir dwi_output/sub-001 \
+  --dti-bmax 1200 \
+  --roi /data/JHU_labels_in_dwi_space.nii.gz
+```
+
+---
+
+## Important Notes & Limitations
+- **Preprocessing matters**: FA/MD are highly sensitive to motion/eddy/susceptibility distortions. Best practice is to run **topup/eddy** first (e.g., via `fsl-tool` or HCP diffusion pipeline) and use the **rotated bvecs** output by eddy.
+- **DTI vs multi-shell**: DTI fitting is most stable on low b-values (commonly b≤1000–1200). Higher-order models (DKI/NODDI) require separate implementations (extend this tool if needed).
+- **ROI alignment**: ROI/atlas labels must be in the *same voxel space* as the DWI-derived metrics. Registration/warping is handled by other tools (e.g., FSL/ANTs/HCP pipelines).
+- **Numerical stability**: small negative eigenvalues can occur; this pipeline clips them to zero before FA computation.
+
+## Benchmark Adapter Guidance
+
+For benchmark-style ROI-statistics tasks, treat this tool as a library of narrow downstream building blocks rather than a mandatory full DWI pipeline.
+
+- If the prompt already provides metric maps plus an ROI/atlas image, start directly from `scripts/roi_stats_reference.py` or an equivalent narrow ROI-statistics implementation.
+- Do not automatically prepend DWI loading, masking, or tensor fitting when the required metric maps already exist.
+- Preserve the benchmark output contract: when the task expects separate ROI summary files per metric, write one CSV per selected metric rather than a single combined table unless the prompt explicitly asks for a merged export.
+
+---
+
+## Complementary / Related Skills
+- `dependency-planner` + `conda-env-manager` → install/manage `neuroclaw-dipy`
+
+---
+
+## Reference
+- DIPY documentation: https://dipy.org/documentation/latest/
+- DIPY DTI reconstruction examples (tensor fitting + FA/MD/AD/RD)
+- rs-fMRI-Pipeline-Tutorial: https://github.com/Karcen/rs-fMRI-Pipeline-Tutorial
+- Curated code snippets in this skill:
+    - `skills/dipy-tool/scripts/load_and_mask_reference.py`
+    - `skills/dipy-tool/scripts/dti_metrics_reference.py`
+    - `skills/dipy-tool/scripts/roi_stats_reference.py`
+- Aligned with NeuroClaw base/tool skill pattern (`mne-eeg-tool`, etc.)
+
+## Post-Execution Verification (Harness Integration)
+
+After DIPY 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="dipy_dti_processing")
+
+# 1. DWI file loading and shape validation
+verifier.add_check("dwi_loading",
+    checker=lambda: verify_dwi_loaded(output_dir),
+    severity="error"
+)
+
+# 2. Brain mask existence and coverage
+verifier.add_check("brain_mask",
+    checker=lambda: verify_brain_mask(output_dir),
+    severity="error"
+)
+
+# 3. Gradient table validity (bvals/bvecs)
+verifier.add_check("gradient_table",
+    checker=lambda: verify_gradient_table(output_dir),
+    severity="error"
+)
+
+# 4. Tensor metrics bounds (FA: 0–1, MD/AD/RD: reasonable μm²/ms)
+verifier.add_check("tensor_bounds",
+    checker=lambda: verify_tensor_metrics_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"
+)
+
+# 6. ROI statistics shape (if extracted)
+verifier.add_check("roi_statistics",
+    checker=lambda: verify_roi_stats_shape(output_dir),
+    severity="warning"
+)
+
+report = verifier.run(output_dir)
+
+# Log verification results
+logger = AuditLogger(log_file=f"{output_dir}/dipy_verification.jsonl")
+logger.log_validation(
+    task_name="dipy_dti_processing",
+    checks_passed=len([r for r in report.results if r.passed]),
+    total_checks=len(report.results),
+    output_path=output_dir
+)
+```
+
+**Output**: `{output_dir}/dipy_verification.jsonl` (structured audit log with JSONL format)
+
+---
+
+Created At: 2026-03-26 00:40 HKT
+Last Updated At: 2026-04-14 00:28 HKT
+Author: chengwang96

package/skills/08_Computational_Neuroscience/dipy-tool/scripts/dti_metrics_reference.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+from dipy.core.gradients import gradient_table
+from dipy.io.gradients import read_bvals_bvecs
+from dipy.io.image import load_nifti, save_nifti
+from dipy.reconst.dti import TensorModel, fractional_anisotropy
+
+
+def fit_dti(data: np.ndarray, bvals: np.ndarray, bvecs: np.ndarray, mask: np.ndarray, b0_threshold: float, dti_bmax: float):
+    keep = (bvals <= dti_bmax) | (bvals < b0_threshold)
+    if not np.any(keep):
+        raise ValueError("No DTI-compatible volumes retained after b-value filtering.")
+
+    gtab = gradient_table(bvals[keep], bvecs[keep], b0_threshold=b0_threshold)
+    model = TensorModel(gtab)
+    return model.fit(data[..., keep], mask=mask.astype(bool))
+
+
+def save_metrics(tenfit, affine: np.ndarray, mask: np.ndarray, output_dir: Path) -> None:
+    evals = np.clip(tenfit.evals, 0, None)
+    fa = fractional_anisotropy(evals)
+    fa[~np.isfinite(fa)] = 0.0
+    fa[mask == 0] = 0.0
+
+    metrics = {
+        "FA.nii.gz": fa.astype(np.float32),
+        "MD.nii.gz": tenfit.md.astype(np.float32),
+        "AD.nii.gz": tenfit.ad.astype(np.float32),
+        "RD.nii.gz": tenfit.rd.astype(np.float32),
+    }
+    for name, values in metrics.items():
+        values[~np.isfinite(values)] = 0.0
+        save_nifti(str(output_dir / name), values, affine)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference DIPY snippet for DTI fitting and FA/MD/AD/RD export.")
+    parser.add_argument("--dwi", type=Path, required=True, help="Input DWI 4D NIfTI.")
+    parser.add_argument("--bval", type=Path, required=True, help="Input bvals file.")
+    parser.add_argument("--bvec", type=Path, required=True, help="Input bvecs file.")
+    parser.add_argument("--mask", type=Path, required=True, help="Brain mask NIfTI in DWI space.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for tensor metrics.")
+    parser.add_argument("--b0-threshold", type=float, default=50.0, help="Threshold for identifying b0 volumes.")
+    parser.add_argument("--dti-bmax", type=float, default=1200.0, help="Max b-value for tensor fitting.")
+    args = parser.parse_args()
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    data, affine = load_nifti(str(args.dwi))
+    bvals, bvecs = read_bvals_bvecs(str(args.bval), str(args.bvec))
+    mask = nib.load(str(args.mask)).get_fdata() > 0
+
+    tenfit = fit_dti(
+        data=data.astype(np.float32),
+        bvals=bvals.astype(float),
+        bvecs=bvecs.astype(float),
+        mask=mask.astype(np.uint8),
+        b0_threshold=args.b0_threshold,
+        dti_bmax=args.dti_bmax,
+    )
+    save_metrics(tenfit, affine, mask.astype(np.uint8), args.output_dir)
+    print(f"Saved tensor metrics to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/08_Computational_Neuroscience/dipy-tool/scripts/load_and_mask_reference.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import nibabel as nib
+import numpy as np
+from dipy.io.gradients import read_bvals_bvecs
+from dipy.io.image import load_nifti, save_nifti
+from dipy.segment.mask import median_otsu
+
+
+def load_dwi(dwi_path: Path, bval_path: Path, bvec_path: Path) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    data, affine = load_nifti(str(dwi_path))
+    bvals, bvecs = read_bvals_bvecs(str(bval_path), str(bvec_path))
+
+    if data.ndim != 4:
+        raise ValueError(f"DWI must be 4D. Got shape={data.shape}")
+    if data.shape[-1] != len(bvals) or data.shape[-1] != len(bvecs):
+        raise ValueError(
+            "Gradient count does not match DWI volumes: "
+            f"volumes={data.shape[-1]}, bvals={len(bvals)}, bvecs={len(bvecs)}"
+        )
+
+    return data.astype(np.float32), affine, bvals.astype(float), bvecs.astype(float)
+
+
+def make_mask(data: np.ndarray, bvals: np.ndarray, affine: np.ndarray, out_mask_path: Path, b0_threshold: float) -> np.ndarray:
+    b0_indices = np.where(bvals < b0_threshold)[0]
+    if b0_indices.size == 0:
+        raise ValueError("No b0 volumes found; cannot build mask with median_otsu.")
+
+    _, mask = median_otsu(data, vol_idx=b0_indices, numpass=4, autocrop=False)
+    save_nifti(str(out_mask_path), mask.astype(np.uint8), affine)
+    return mask.astype(np.uint8)
+
+
+def save_b0_mean(data: np.ndarray, bvals: np.ndarray, affine: np.ndarray, out_path: Path, b0_threshold: float) -> None:
+    b0_indices = np.where(bvals < b0_threshold)[0]
+    if b0_indices.size == 0:
+        raise ValueError("No b0 volumes found; cannot save mean b0 image.")
+    b0_mean = np.mean(data[..., b0_indices], axis=3)
+    nib.save(nib.Nifti1Image(b0_mean.astype(np.float32), affine), str(out_path))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Reference DIPY snippet for DWI loading and brain mask generation.")
+    parser.add_argument("--dwi", type=Path, required=True, help="Input DWI 4D NIfTI.")
+    parser.add_argument("--bval", type=Path, required=True, help="Input bvals file.")
+    parser.add_argument("--bvec", type=Path, required=True, help="Input bvecs file.")
+    parser.add_argument("--output-dir", type=Path, required=True, help="Directory for mask and summary outputs.")
+    parser.add_argument("--b0-threshold", type=float, default=50.0, help="Threshold for identifying b0 volumes.")
+    args = parser.parse_args()
+
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+    data, affine, bvals, bvecs = load_dwi(args.dwi, args.bval, args.bvec)
+    mask = make_mask(data, bvals, affine, args.output_dir / "brain_mask.nii.gz", args.b0_threshold)
+    save_b0_mean(data, bvals, affine, args.output_dir / "mean_b0.nii.gz", args.b0_threshold)
+
+    summary = args.output_dir / "dwi_summary.txt"
+    summary.write_text(
+        "\n".join(
+            [
+                f"shape={data.shape}",
+                f"n_bvals={len(bvals)}",
+                f"n_bvecs={len(bvecs)}",
+                f"mask_voxels={int(mask.sum())}",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    print(f"Saved mask and DWI summary to: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()