8. Reference documentation: all nilearn functions

This is the class and function reference of nilearn. Please refer to the user guide for more information and usage examples.

List of modules

8.1. nilearn.connectome: Functional Connectivity

Tools for computing functional connectivity matrices and also implementation of algorithm for sparse multi subjects learning of Gaussian graphical models.


ConnectivityMeasure([cov_estimator, kind, …])

A class that computes different kinds of functional connectivity matrices.

GroupSparseCovariance([alpha, tol, …])

Covariance and precision matrix estimator.

GroupSparseCovarianceCV([alphas, …])

Sparse inverse covariance w/ cross-validated choice of the parameter.


sym_matrix_to_vec(symmetric[, discard_diagonal])

Return the flattened lower triangular part of an array.

vec_to_sym_matrix(vec[, diagonal])

Return the symmetric matrix given its flattened lower triangular part.

group_sparse_covariance(subjects, alpha[, …])

Compute sparse precision matrices and covariance matrices.


Return correlation matrix for a given covariance matrix.


Return partial correlation matrix for a given precision matrix.

8.2. nilearn.datasets: Automatic Dataset Fetching

Helper functions to download NeuroImaging datasets

User guide: See the Fetching open datasets from Internet section for further details.


fetch_atlas_craddock_2012([data_dir, url, …])

Download and return file names for the Craddock 2012 parcellation

fetch_atlas_destrieux_2009([lateralized, …])

Download and load the Destrieux cortical atlas (dated 2009)

fetch_atlas_harvard_oxford(atlas_name[, …])

Load Harvard-Oxford parcellations from FSL.

fetch_atlas_juelich(atlas_name[, data_dir, …])

Load Juelich parcellations from FSL.

fetch_atlas_msdl([data_dir, url, resume, …])

Download and load the MSDL brain atlas.

fetch_atlas_difumo([dimension, …])

Fetch DiFuMo brain atlas


Download and load the Power et al. brain atlas composed of 264 ROIs.


Load the Seitzman et al. 300 ROIs.

fetch_atlas_smith_2009([data_dir, mirror, …])

Download and load the Smith ICA and BrainMap atlas (dated 2009).

fetch_atlas_yeo_2011([data_dir, url, …])

Download and return file names for the Yeo 2011 parcellation.

fetch_atlas_aal([version, data_dir, url, …])

Downloads and returns the AAL template for SPM 12.

fetch_atlas_basc_multiscale_2015([version, …])

Downloads and loads multiscale functional brain parcellations

fetch_atlas_allen_2011([data_dir, url, …])

Download and return file names for the Allen and MIALAB ICA atlas (dated 2011).

fetch_atlas_pauli_2017([version, data_dir, …])

Download the Pauli et al. (2017) atlas with in total 12 subcortical nodes.


Load the Dosenbach et al. 160 ROIs.

fetch_abide_pcp([data_dir, n_subjects, …])

Fetch ABIDE dataset.

fetch_adhd([n_subjects, data_dir, url, …])

Download and load the ADHD resting-state dataset.

fetch_development_fmri([n_subjects, …])

Fetch movie watching based brain development dataset (fMRI)

fetch_haxby([data_dir, subjects, …])

Download and loads complete haxby dataset.

fetch_icbm152_2009([data_dir, url, resume, …])

Download and load the ICBM152 template (dated 2009).

fetch_icbm152_brain_gm_mask([data_dir, …])

Downloads ICBM152 template first, then loads the ‘gm’ mask.

fetch_localizer_button_task([data_dir, url, …])

Fetch left vs right button press contrast maps from the localizer.

fetch_localizer_contrasts(contrasts[, …])

Download and load Brainomics/Localizer dataset (94 subjects).


Fetch calculation task contrast maps from the localizer.

fetch_miyawaki2008([data_dir, url, resume, …])

Download and loads Miyawaki et al. 2008 dataset (153MB).

fetch_surf_nki_enhanced([n_subjects, …])

Download and load the NKI enhanced resting-state dataset, preprocessed and projected to the fsaverage5 space surface.

fetch_surf_fsaverage([mesh, data_dir])

Download a Freesurfer fsaverage surface.

fetch_atlas_surf_destrieux([data_dir, url, …])

Download and load Destrieux et al, 2010 cortical atlas

fetch_atlas_talairach(level_name[, …])

Download the Talairach atlas.

fetch_atlas_schaefer_2018([n_rois, …])

Download and return file names for the Schaefer 2018 parcellation

fetch_oasis_vbm([n_subjects, …])

Download and load Oasis “cross-sectional MRI” dataset (416 subjects).

fetch_megatrawls_netmats([dimensionality, …])

Downloads and returns Network Matrices data from MegaTrawls release in HCP.

fetch_cobre([n_subjects, data_dir, url, verbose])

DEPRECATED: ‘fetch_cobre’ has been deprecated and will be removed in release 0.9 .

fetch_neurovault([max_images, …])

Download data from neurovault.org that match certain criteria.

fetch_neurovault_ids([collection_ids, …])

Download specific images and collections from neurovault.org.


Fetch a contrast map from NeuroVault showing the effect of mental subtraction upon auditory instructions

fetch_neurovault_motor_task([data_dir, verbose])

Fetch left vs right button press group contrast map from NeuroVault.


Returns the directories in which nilearn looks for data.


Load the MNI152 skullstripped T1 template.


Load the MNI152 grey-matter template.


Load the MNI152 white-matter template.

load_mni152_brain_mask([resolution, threshold])

Load the MNI152 whole-brain mask.

load_mni152_gm_mask([resolution, threshold, …])

Load the MNI152 grey-matter mask.

load_mni152_wm_mask([resolution, threshold, …])

Load the MNI152 white-matter mask.


Download language localizer demo dataset.

fetch_bids_langloc_dataset([data_dir, verbose])

Download language localizer example bids dataset.

fetch_openneuro_dataset_index([data_dir, …])

Download a file with OpenNeuro BIDS dataset index.

select_from_index(urls[, inclusion_filters, …])

Select subset of urls with given filters.


Add symlinks for files not named according to latest BIDS conventions.

fetch_openneuro_dataset([urls, data_dir, …])

Download OpenNeuro BIDS dataset.

fetch_localizer_first_level([data_dir, verbose])

Download a first-level localizer fMRI dataset

fetch_spm_auditory([data_dir, data_name, …])

Function to fetch SPM auditory single-subject data.

fetch_spm_multimodal_fmri([data_dir, …])

Fetcher for Multi-modal Face Dataset.

fetch_fiac_first_level([data_dir, verbose])

Download a first-level fiac fMRI dataset (2 sessions)

8.3. nilearn.decoding: Decoding

Decoding tools and algorithms.


Decoder([estimator, mask, cv, param_grid, …])

A wrapper for popular classification strategies in neuroimaging.

DecoderRegressor([estimator, mask, cv, …])

A wrapper for popular regression strategies in neuroimaging.

FREMClassifier([estimator, mask, cv, …])

State of the art decoding scheme applied to usual classifiers.

FREMRegressor([estimator, mask, cv, …])

State of the art decoding scheme applied to usual regression estimators.

SpaceNetClassifier([penalty, loss, …])

Classification learners with sparsity and spatial priors.

SpaceNetRegressor([penalty, l1_ratios, …])

Regression learners with sparsity and spatial priors.

SearchLight(mask_img[, process_mask_img, …])

Implement search_light analysis using an arbitrary type of classifier.

8.4. nilearn.decomposition: Multivariate Decompositions

The nilearn.decomposition module includes a subject level variant of the ICA called Canonical ICA.


CanICA([mask, n_components, smoothing_fwhm, …])

Perform Canonical Independent Component Analysis [R637c2563345c-1] [R637c2563345c-2].

DictLearning([n_components, n_epochs, …])

Perform a map learning algorithm based on spatial component sparsity, over a CanICA initialization [Rd0eec3116114-1].

8.5. nilearn.image: Image Processing and Resampling Utilities

Mathematical operations working on Niimg-like objects like a (3+)D block of data, and an affine.


binarize_img(img[, threshold, mask_img])

Binarize an image such that its values are either 0 or 1.

clean_img(imgs[, sessions, detrend, …])

Improve SNR on masked fMRI signals.

concat_imgs(niimgs[, dtype, ensure_ndim, …])

Concatenate a list of 3D/4D niimgs of varying lengths.

coord_transform(x, y, z, affine)

Convert the x, y, z coordinates from one image space to another


Copy an image to a nibabel.Nifti1Image.

crop_img(img[, rtol, copy, pad, return_offset])

Crops an image as much as possible.


Get the image data as a numpy.ndarray.

high_variance_confounds(imgs[, n_confounds, …])

Return confounds signals extracted from input signals with highest variance.

index_img(imgs, index)

Indexes into a 4D Niimg-like object in the fourth dimension.


Iterates over a 4D Niimg-like object in the fourth dimension.


Return the largest connected component of an image or list of images.

load_img(img[, wildcards, dtype])

Load a Niimg-like object from filenames or list of filenames.

math_img(formula, **imgs)

Interpret a numpy based string formula using niimg in named parameters.

mean_img(imgs[, target_affine, …])

Compute the mean of the images over time or the 4th dimension.

new_img_like(ref_niimg, data[, affine, …])

Create a new image of the same class as the reference image

resample_img(img[, target_affine, …])

Resample a Niimg-like object

resample_to_img(source_img, target_img[, …])

Resample a Niimg-like source image on a target Niimg-like image (no registration is performed: the image should already be aligned).

reorder_img(img[, resample])

Returns an image with the affine diagonal (by permuting axes).

smooth_img(imgs, fwhm)

Smooth images by applying a Gaussian filter.


Performs swapping of hemispheres in the indicated NIfTI image.

threshold_img(img, threshold[, mask_img, copy])

Threshold the given input image, mostly statistical or atlas images.

8.6. nilearn.input_data: Loading and Processing Files Easily

The nilearn.input_data module includes scikit-learn tranformers and tools to preprocess neuro-imaging data.

User guide: See the NiftiMasker: applying a mask to load time-series section for further details.


NiftiMasker([mask_img, runs, …])

Applying a mask to extract time-series from Niimg-like objects.

MultiNiftiMasker([mask_img, smoothing_fwhm, …])

Class for masking of Niimg-like objects.

NiftiLabelsMasker(labels_img[, labels, …])

Class for masking of Niimg-like objects.

NiftiMapsMasker(maps_img[, mask_img, …])

Class for masking of Niimg-like objects.

NiftiSpheresMasker(seeds[, radius, …])

Class for masking of Niimg-like objects using seeds.

8.7. nilearn.masking: Data Masking Utilities

Utilities to compute and operate on brain masks

User guide: See the Masking the data: from 4D image to 2D array section for further details.


compute_epi_mask(epi_img[, lower_cutoff, …])

Compute a brain mask from fMRI data in 3D or 4D ndarrays.

compute_multi_epi_mask(epi_imgs[, …])

Compute a common mask for several sessions or subjects of fMRI data.

compute_brain_mask(target_img[, threshold, …])

Compute the whole-brain, grey-matter or white-matter mask.

compute_multi_brain_mask(target_imgs[, …])

Compute the whole-brain, grey-matter or white-matter mask for a list of images.

compute_background_mask(data_imgs[, …])

Compute a brain mask for the images by guessing the value of the background from the border of the image.

compute_multi_background_mask(data_imgs[, …])

Compute a common mask for several sessions or subjects of data.

intersect_masks(mask_imgs[, threshold, …])

Compute intersection of several masks

apply_mask(imgs, mask_img[, dtype, …])

Extract signals from images using specified mask.

unmask(X, mask_img[, order])

Take masked data and bring them back into 3D/4D

8.8. nilearn.regions: Operating on Regions

The nilearn.regions class module includes region extraction procedure on a 4D statistical/atlas maps and its function.


connected_regions(maps_img[, …])

Extraction of brain connected regions into separate regions.

connected_label_regions(labels_img[, …])

Extract connected regions from a brain atlas image defined by labels (integers).

img_to_signals_labels(imgs, labels_img[, …])

Extract region signals from image.

signals_to_img_labels(signals, labels_img[, …])

Create image from region signals defined as labels.

img_to_signals_maps(imgs, maps_img[, mask_img])

Extract region signals from image.

signals_to_img_maps(region_signals, maps_img)

Create image from region signals defined as maps.


RegionExtractor(maps_img[, mask_img, …])

Class for brain region extraction.

Parcellations(method[, n_parcels, …])

Learn parcellations on fMRI images.

ReNA(mask_img[, n_clusters, scaling, …])

Recursive Neighbor Agglomeration (ReNA): Recursively merges the pair of clusters according to 1-nearest neighbors criterion.

8.9. nilearn.mass_univariate: Mass-Univariate Analysis

Defines a Massively Univariate Linear Model estimated with OLS and permutation test


permuted_ols(tested_vars, target_vars[, …])

Massively univariate group analysis with permuted OLS.

8.10. nilearn.plotting: Plotting Brain Data

Plotting code for nilearn


find_cut_slices(img[, direction, n_cuts, …])

Find ‘good’ cross-section slicing positions along a given axis.

find_xyz_cut_coords(img[, mask_img, …])

Find the center of the largest activation connected component.

find_parcellation_cut_coords(labels_img[, …])

Return coordinates of center of mass of 3D parcellation atlas.


Return coordinates of center probabilistic atlas 4D image.

plot_anat([anat_img, cut_coords, …])

Plot cuts of an anatomical image (by default 3 cuts: Frontal, Axial, and Lateral)

plot_img(img[, cut_coords, output_file, …])

Plot cuts of a given image (by default Frontal, Axial, and Lateral)

plot_epi([epi_img, cut_coords, output_file, …])

Plot cuts of an EPI image (by default 3 cuts: Frontal, Axial, and Lateral)

plot_matrix(mat[, title, labels, figure, …])

Plot the given matrix.

plot_roi(roi_img[, bg_img, cut_coords, …])

Plot cuts of an ROI/mask image (by default 3 cuts: Frontal, Axial, and Lateral)

plot_stat_map(stat_map_img[, bg_img, …])

Plot cuts of an ROI/mask image (by default 3 cuts: Frontal, Axial, and Lateral)

plot_glass_brain(stat_map_img[, …])

Plot 2d projections of an ROI/mask image (by default 3 projections: Frontal, Axial, and Lateral).

plot_connectome(adjacency_matrix, node_coords)

Plot connectome on top of the brain glass schematics.

plot_connectome_strength(adjacency_matrix, …)

Plot connectome strength on top of the brain glass schematics.

plot_markers(node_values, node_coords[, …])

Plot network nodes (markers) on top of the brain glass schematics.

plot_prob_atlas(maps_img[, bg_img, …])

Plot the probabilistic atlases onto the anatomical image by default MNI template

plot_carpet(img[, mask_img, mask_labels, …])

Plot an image representation of voxel intensities across time.

plot_surf(surf_mesh[, surf_map, bg_map, …])

Plotting of surfaces with optional background and data

plot_surf_roi(surf_mesh, roi_map[, bg_map, …])

Plotting ROI on a surface mesh with optional background

plot_surf_contours(surf_mesh, roi_map[, …])

Plotting contours of ROIs on a surface, optionally over a statistical map.

plot_surf_stat_map(surf_mesh, stat_map[, …])

Plotting a stats map on a surface mesh with optional background

plot_img_on_surf(stat_map[, surf_mesh, …])

Convenience function to plot multiple views of plot_surf_stat_map in a single figure.

plot_img_comparison(ref_imgs, src_imgs, masker)

Creates plots to compare two lists of images and measure correlation.

plot_design_matrix(design_matrix[, rescale, …])

Plot a design matrix provided as a DataFrame

plot_event(model_event[, cmap, output_file])

Creates plot for event visualization.

plot_contrast_matrix(contrast_def, design_matrix)

Creates plot for contrast definition.

view_surf(surf_mesh[, surf_map, bg_map, …])

Insert a surface plot of a surface map into an HTML page.

view_img_on_surf(stat_map_img[, surf_mesh, …])

Insert a surface plot of a statistical map into an HTML page.

view_connectome(adjacency_matrix, node_coords)

Insert a 3d plot of a connectome into an HTML page.

view_markers(marker_coords[, marker_color, …])

Insert a 3d plot of markers in a brain into an HTML page.

view_img(stat_map_img[, bg_img, cut_coords, …])

Interactive html viewer of a statistical map, with optional background.


Show all the figures generated by nilearn and/or matplotlib.


OrthoSlicer(cut_coords[, axes, black_bg, …])

A class to create 3 linked axes for plotting orthogonal cuts of 3D maps.

8.11. nilearn.signal: Preprocessing Time Series

Preprocessing functions for time series.

All functions in this module should take X matrices with samples x features


clean(signals[, runs, detrend, standardize, …])

Improve SNR on masked fMRI signals.

high_variance_confounds(series[, …])

Return confounds time series extracted from series with highest variance.

8.12. nilearn.glm: Generalized Linear Models

Analysing fMRI data using GLMs.

Note that the nilearn.glm module is experimental.

It may change in any future (>0.7.0) release of Nilearn.


Contrast(effect, variance[, dim, dof, …])

The contrast class handles the estimation of statistical contrasts on a given model: student (t) or Fisher (F).

FContrastResults(effect, covariance, F, df_num)

Results from an F contrast of coefficients in a parametric model.

TContrastResults(t, sd, effect[, df_den])

Results from a t contrast of coefficients in a parametric model.

ARModel(design, rho)

A regression model with an AR(p) covariance structure.


A simple ordinary least squares model.

LikelihoodModelResults(theta, Y, model[, …])

Class to contain results from likelihood models.

RegressionResults(theta, Y, model, …[, …])

This class summarizes the fit of a linear regression model.


This class contains only information of the model fit necessary for contrast computation.


compute_contrast(labels, regression_result, …)

Compute the specified contrast given an estimated glm

compute_fixed_effects(contrast_imgs, …[, …])

Compute the fixed effects, given images of effects and variance

expression_to_contrast_vector(expression, …)

Converts a string describing a contrast to a contrast vector

fdr_threshold(z_vals, alpha)

Return the Benjamini-Hochberg FDR threshold for the input z_vals

cluster_level_inference(stat_img[, …])

Report the proportion of active voxels for all clusters defined by the input threshold.

threshold_stats_img([stat_img, mask_img, …])

Compute the required threshold level and return the thresholded map

8.12.15. nilearn.glm.first_level


FirstLevelModel([t_r, slice_time_ref, …])

Implementation of the General Linear Model for single session fMRI data.



Check that the provided DataFrame is indeed a valid design matrix descriptor, and returns a triplet of fields

compute_regressor(exp_condition, hrf_model, …)

This is the main function to convolve regressors with hrf model

first_level_from_bids(dataset_path, task_label)

Create FirstLevelModel objects and fit arguments from a BIDS dataset.

glover_dispersion_derivative(tr[, …])

Implementation of the Glover dispersion derivative hrf model

glover_hrf(tr[, oversampling, time_length, …])

Implementation of the Glover hrf model

glover_time_derivative(tr[, oversampling, …])

Implementation of the Glover time derivative hrf (dhrf) model


Generate a design matrix from the input parameters

mean_scaling(Y[, axis])

Scaling of the data to have percent of baseline change along the specified axis

run_glm(Y, X[, noise_model, bins, n_jobs, …])

GLM fit for an fMRI data matrix

spm_dispersion_derivative(tr[, …])

Implementation of the SPM dispersion derivative hrf model

spm_hrf(tr[, oversampling, time_length, onset])

Implementation of the SPM hrf model

spm_time_derivative(tr[, oversampling, …])

Implementation of the SPM time derivative hrf (dhrf) model

8.12.16. nilearn.glm.second_level


SecondLevelModel([mask_img, target_affine, …])

Implementation of the General Linear Model for multiple subject fMRI data



Sets up a second level design.


Generate p-values corresponding to the contrasts provided based on permutation testing.

8.13. nilearn.reporting: Reporting Functions

Reporting code for nilearn


get_clusters_table(stat_img, stat_threshold)

Creates pandas dataframe with img cluster statistics.

make_glm_report(model, contrasts[, title, …])

Returns HTMLReport object for a report which shows all important aspects of a fitted GLM.

8.14. nilearn.surface: Manipulating Surface Data

Functions for surface manipulation.



Loading data to be represented on a surface mesh.


Loading a surface mesh geometry

vol_to_surf(img, surf_mesh[, radius, …])

Extract surface data from a Nifti image.