Nilearn

Nilearn

Nilearn provides neuroimaging-focused building blocks on top of NumPy/scikit-learn for image processing, statistical modeling, decoding, and connectivity workflows.

Version

Built against: nilearn==0+unknown Python: 3.13

Source checkout uses dynamic versioning; see assets/version.txt for commit and environment details.

Scope

This skill intentionally focuses on high-usage workflows across datasets, image, maskers, glm, decoding, connectome, plotting, surface, and interfaces.

Out of scope in this skill: private _utils, low-level test helpers, and exhaustive coverage of every plotting backend edge case.

Coverage profile: hybrid (workflow references + dictionary lookup assets).

Environment Gate

Install policy and environment decision are recorded in assets/version.txt. Current build used install_permission: no, so runtime claims are tagged where relevant.

Installation

# requires explicit install permission
pip install nilearn

# optional plotting stack for visualization-heavy workflows
pip install "nilearn[plotting]"

Datasets and Atlases

# tested against nilearn==0+unknown
try:
    from nilearn import datasets
    template = datasets.load_mni152_template()
    print(template.shape)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/datasets-and-atlases.md for fetchers, template loaders, and version-specific dataset deprecations.

Image Manipulation

# tested against nilearn==0+unknown
try:
    import numpy as np
    import nibabel as nib
    from nilearn.image import math_img

    img = nib.Nifti1Image(np.ones((4, 4, 4), dtype=float), np.eye(4))
    doubled = math_img("img * 2", img=img)
    print(doubled.shape)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/image-manipulation.md for smooth_img, math_img, and resample_to_img usage and caveats.

Maskers and Signals

# tested against nilearn==0+unknown
try:
    from nilearn.maskers import NiftiMasker
    masker = NiftiMasker(standardize=True, detrend=True)
    print(type(masker).__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/maskers-and-signals.md for NiftiMasker/NiftiLabelsMasker signatures and migration notes.

GLM Modeling

# tested against nilearn==0+unknown
try:
    from nilearn.glm.first_level import FirstLevelModel
    model = FirstLevelModel(t_r=2.0, noise_model="ar1")
    print(type(model).__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/glm-modeling.md for FirstLevelModel, SecondLevelModel, and threshold_stats_img behavior.

Decoding and Connectivity

# tested against nilearn==0+unknown
try:
    from nilearn.decoding import Decoder
    from nilearn.connectome import ConnectivityMeasure

    print(Decoder.__name__, ConnectivityMeasure.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/decoding-and-connectivity.md for Decoder, SearchLight, and ConnectivityMeasure parameter patterns.

Plotting and Visualization

# tested against nilearn==0+unknown
try:
    # REQUIRES: pip install "nilearn[plotting]"
    from nilearn.plotting import plot_stat_map, view_img
    print(plot_stat_map.__name__, view_img.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/plotting-and-visualization.md for plot_img, plot_stat_map, view_img, and surface plotting viewers.

Surface Workflows

# tested against nilearn==0+unknown
try:
    from nilearn.surface import vol_to_surf, SurfaceImage
    print(vol_to_surf.__name__, SurfaceImage.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/surface-workflows.md for vol_to_surf, mesh/data loaders, and SurfaceImage patterns.

Interfaces (BIDS/fMRIPrep)

# tested against nilearn==0+unknown
try:
    from nilearn.interfaces.bids import get_bids_files
    from nilearn.interfaces.fmriprep import load_confounds
    print(get_bids_files.__name__, load_confounds.__name__)
except Exception as e:
    print(f"[UNVERIFIED: install denied in selected environment] {type(e).__name__}: {e}")

See references/interfaces-bids-and-fmriprep.md for BIDS queries, confounds loading, and first_level_from_bids usage.

Verification (Medium+)

PYTHONPATH="H:\Agent\OpenSciHub\nilearn" python "H:\Agent\OpenSciHub\.opencode\skills\opensci-skill\scripts\verify-snippets.py" --root "H:\Agent\OpenSciHub\.opencode\skills\nilearn" --fail-fast

Dictionary Assets (Hybrid)

Use dictionary assets before source traversal for symbol-level lookup:

1. Query assets/symbol-index.jsonl for exact symbol names.
2. Open the matching module card in assets/symbol-cards/.
3. Follow source anchors in the card only when implementation details are needed.

Primary dictionary entrypoint: assets/symbol-index.md.

Quick Reference

Module Map

Import style: explicit __all__ submodule list in nilearn.__init__ (no top-level star re-export of function symbols).

See assets/module-map.md for full inventory and [LARGE] module flags.

References

• references/datasets-and-atlases.md - template loading, atlas fetchers, and dataset deprecation path.
• references/image-manipulation.md - image-level transforms (smooth_img, math_img, resample_to_img).
• references/maskers-and-signals.md - masker constructors and signal extraction controls.
• references/glm-modeling.md - first/second-level GLM and thresholding function contract.
• references/decoding-and-connectivity.md - decoding wrappers and connectivity estimator patterns.
• references/plotting-and-visualization.md - stat-map, surface plots, and interactive viewers.
• references/surface-workflows.md - surface mesh/data loading and volume projection workflows.
• references/interfaces-bids-and-fmriprep.md - BIDS querying, confounds interfaces, and BIDS-to-GLM bootstrapping.
• assets/symbol-index.md - dictionary-style module index for broad API lookup.
• assets/symbol-index.jsonl - machine-readable symbol registry.
• assets/symbol-cards/ - per-module symbol cards with signatures and source anchors.