---

name: data-io-signal description: "Handle Nilearn Niimg image I/O, volume image operations, masking/unmasking, and signal cleaning with tiny no-network checks." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

Nilearn Data I/O and Signal Skill

Use this sub-skill when the task is about low-level Nilearn volume images and array time series: loading 3D/4D Niimg inputs, creating new NIfTI images, resampling, smoothing, thresholding, applying or computing masks, and cleaning signals with confounds or sample masks.

Route Tasks

• Image input validation: Use nilearn.image.load_img and nilearn.image.check_niimg for path, glob, pathlib.Path, or in-memory nibabel inputs. See data formats and API reference.
• Image transforms: Use index_img, iter_img, concat_imgs, mean_img, new_img_like, math_img, resample_img, resample_to_img, smooth_img, threshold_img, and clean_img. See workflows.
• Masking: Use compute_epi_mask, compute_background_mask, compute_brain_mask, intersect_masks, apply_mask, and unmask for direct image-to-array workflows. See API reference.
• Signal arrays: Use nilearn.signal.clean for 2D arrays shaped (n_samples, n_features), confounds, run labels, temporal filtering, scrubbing, and standardization. See data formats.
• Smoke checks: Run the bundled no-network script: python scripts/smoke_image_signal.py from this sub-skill directory.

Boundaries

• Route estimator objects such as NiftiMasker, labels/spheres maskers, region extraction, and scikit-learn pipeline integration to maskers-regions.
• Route surface mesh/image workflows, SurfaceImage, and vol_to_surf to surface-workflows.
• Route plotting displays, reports, HTML views, and figure export to plotting-reporting.
• Keep examples no-network by generating tiny numpy arrays and nibabel.Nifti1Image objects in memory.

Quick Checklist

1. Confirm dimensionality with check_niimg(..., ensure_ndim=3 or 4) before assuming a 3D map or 4D run.
2. Compare both shape[:3] and affine before apply_mask; resample to a shared field of view before masking.
3. Ensure masks are 3D, binary, non-empty, and in the same field of view as the image.
4. Treat apply_mask output as (n_samples, n_voxels) and signal.clean input as (n_samples, n_features).
5. Pass t_r when using temporal filters (low_pass or high_pass) and make confounds/sample masks align to the original number of time points.

References

• API reference
• Workflows
• Data formats
• Troubleshooting
• Smoke script