---
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)
---

# 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.**

---

## 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.

---

## 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`

Created At: 2026-03-26 0:54 HKT
Last Updated At: 2026-03-26 0:54 HKT
Author: chengwang96