Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.maskers.NiftiMasker¶

class nilearn.maskers.NiftiMasker(mask_img=None, runs=None, smoothing_fwhm=None, standardize=False, standardize_confounds=True, detrend=False, high_variance_confounds=False, low_pass=None, high_pass=None, t_r=None, target_affine=None, target_shape=None, mask_strategy='background', mask_args=None, dtype=None, memory_level=1, memory=None, verbose=0, reports=True, **kwargs)[source]¶

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

NiftiMasker is useful when preprocessing (detrending, standardization, resampling, etc.) of in-mask voxels is necessary.

Use case: working with time series of resting-state or task maps.

Parameters:

mask_imgNiimg-like object, optional

See Input and output: neuroimaging data representation. Mask for the data. If not given, a mask is computed in the fit step. Optional parameters (mask_args and mask_strategy) can be set to fine tune the mask extraction. If the mask and the images have different resolutions, the images are resampled to the mask resolution. If target_shape and/or target_affine are provided, the mask is resampled first. After this, the images are resampled to the resampled mask.

runsnumpy.ndarray, optional

Add a run level to the preprocessing. Each run will be detrended independently. Must be a 1D array of n_samples elements.

smoothing_fwhmfloat, optional.

If smoothing_fwhm is not None, it gives the full-width at half maximum in millimeters of the spatial smoothing to apply to the signal.

standardize{‘zscore_sample’, ‘zscore’, ‘psc’, True, False}, default=False

Strategy to standardize the signal:

'zscore_sample': The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses sample std.
'zscore': The signal is z-scored. Timeseries are shifted to zero mean and scaled to unit variance. Uses population std by calling default numpy.std with N - ddof=0.
'psc': Timeseries are shifted to zero mean value and scaled to percent signal change (as compared to original mean signal).
True: The signal is z-scored (same as option zscore). Timeseries are shifted to zero mean and scaled to unit variance.
False: Do not standardize the data.

standardize_confoundsbool, default=True

If set to True, the confounds are z-scored: their mean is put to 0 and their variance to 1 in the time dimension.

high_variance_confoundsbool, default=False

If True, high variance confounds are computed on provided image with nilearn.image.high_variance_confounds and default parameters and regressed out.

detrendbool, optional

Whether to detrend signals or not.

low_passfloat or None, default=None

Low cutoff frequency in Hertz. If specified, signals above this frequency will be filtered out. If None, no low-pass filtering will be performed.

high_passfloat, default=None

High cutoff frequency in Hertz. If specified, signals below this frequency will be filtered out.

t_rfloat or None, default=None

Repetition time, in seconds (sampling period). Set to None if not provided.

target_affine3x3 or 4x4 numpy.ndarray, optional

This parameter is passed to image.resample_img. Please see the related documentation for details.

target_shape3-tuple of int, optional

This parameter is passed to image.resample_img. Please see the related documentation for details.

mask_strategy{“background”, “epi”, “whole-brain-template”,”gm-template”, “wm-template”}, optional

The strategy used to compute the mask:

"background": Use this option if your images present a clear homogeneous background.
"epi": Use this option if your images are raw EPI images
"whole-brain-template": This will extract the whole-brain part of your data by resampling the MNI152 brain mask for your data’s field of view.

Note

This option is equivalent to the previous ‘template’ option which is now deprecated.
"gm-template": This will extract the gray matter part of your data by resampling the corresponding MNI152 template for your data’s field of view.

Added in version 0.8.1.
"wm-template": This will extract the white matter part of your data by resampling the corresponding MNI152 template for your data’s field of view.

Added in version 0.8.1:

Note

Depending on this value, the mask will be computed from nilearn.masking.compute_background_mask, nilearn.masking.compute_epi_mask, or nilearn.masking.compute_brain_mask.

Default=’background’.

mask_argsdict, optional

If mask is None, these are additional parameters passed to nilearn.masking.compute_background_mask, or nilearn.masking.compute_epi_mask to fine-tune mask computation. Please see the related documentation for details.

dtype{dtype, “auto”}, optional

Data type toward which the data should be converted. If “auto”, the data will be converted to int32 if dtype is discrete and float32 if it is continuous.

memoryNone, instance of joblib.Memory, str, or pathlib.Path

Used to cache the masking process. By default, no caching is done. If a str is given, it is the path to the caching directory.

memory_levelint, default=1

Rough estimator of the amount of memory used by caching. Higher value means more memory for caching. Zero means no caching.

verboseint, default=0

Verbosity level (0 means no message).

reportsbool, default=True

If set to True, data is saved in order to produce a report.

kwargsdict

Keyword arguments to be passed to functions called within the masker. Kwargs prefixed with ‘clean__’ will be passed to clean. Within clean, kwargs prefixed with ‘butterworth__’ will be passed to the Butterworth filter (i.e., clean__butterworth__).

Attributes:

mask_img_nibabel.nifti1.Nifti1Image: The mask of the data, or the computed one.
affine_4x4 numpy.ndarray: Affine of the transformed image.
n_elements_int: The number of voxels in the mask.

Added in version 0.9.2.

Examples using `nilearn.maskers.NiftiMasker`¶

The haxby dataset: different multi-class strategies

Searchlight analysis of face vs house recognition

ROI-based decoding analysis in Haxby et al. dataset

Voxel-Based Morphometry on Oasis dataset

Understanding Decoder

Encoding models for visual stimuli from Miyawaki et al. 2008

Reconstruction of visual stimuli from Miyawaki et al. 2008

Producing single subject maps of seed-to-voxel correlation

First level analysis of a complete BIDS dataset from openneuro

Simple example of NiftiMasker use

Understanding NiftiMasker and mask computation

Multivariate decompositions: Independent component analysis of fMRI

Massively univariate analysis of a calculation task from the Localizer dataset

NeuroVault cross-study ICA maps

Massively univariate analysis of a motor task from the Localizer dataset

Massively univariate analysis of face vs house recognition

Advanced decoding using scikit learn

Beta-Series Modeling for Task-Based Functional Connectivity and Decoding

nilearn.maskers.NiftiMasker¶

Examples using nilearn.maskers.NiftiMasker¶

Examples using `nilearn.maskers.NiftiMasker`¶