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 --> 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 ```bash # requires explicit install permission pip install nilearn # optional plotting stack for visualization-heavy workflows pip install "nilearn[plotting]" ``` --- ## Datasets and Atlases ```python # 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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 ```python # 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) ```python # 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+) ```bash 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 | Function / Class | Purpose | |-----------------|---------| | `datasets.load_mni152_template()` | Load canonical skull-stripped MNI template image. | | `datasets.fetch_atlas_schaefer_2018()` | Download Schaefer atlas files and labels bundle. | | `image.math_img()` | Apply NumPy expressions directly to image data. | | `maskers.NiftiMasker` | Fit/apply voxel masks and clean extracted time series. | | `glm.first_level.FirstLevelModel` | Build subject-level fMRI GLM from events/designs. | | `decoding.Decoder` | Cross-validated decoding wrapper over Niimg inputs. | | `connectome.ConnectivityMeasure` | Estimate covariance/correlation/tangent connectomes. | | `plotting.plot_stat_map()` | Plot thresholded statistical maps on anatomy. | | `surface.vol_to_surf()` | Project volumetric data onto cortical surfaces. | | `interfaces.fmriprep.load_confounds()` | Build denoising regressors from fMRIPrep outputs. | --- ## Module Map | Submodule | Contents | Notes | |-----------|----------|-------| | `nilearn.datasets` | built-in samples + remote fetchers | Large public surface | | `nilearn.image` | math, smoothing, resampling, concat | Core image transforms | | `nilearn.maskers` | signal extraction transformers | Main user preprocessing entry | | `nilearn.glm` | first/second-level stats models | Large API with many defaults | | `nilearn.decoding` | decoders, searchlight, space-net | ML workflows | | `nilearn.connectome` | connectivity estimators | feature-level connectomes | | `nilearn.plotting` | static and interactive viewers | Often requires plotting extras | | `nilearn.surface` | mesh I/O and volume-to-surface projection | Surface-specific data model | | `nilearn.interfaces` | BIDS and fMRIPrep integration utilities | Pipeline orchestration helpers | 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.