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:

conda activate neuroclaw
conda install -n neuroclaw -c conda-forge nibabel numpy pandas -y

Optional companion packages for downstream workflows:

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:

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:

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:

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