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_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 ‘gm’ mask image.

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 skullstripped 2mm version of the MNI152 originally distributed with FSL.


Load brain mask from MNI152 T1 template


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.


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


Compute a mask corresponding to the gray matter part of the brain 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 contast 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.