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.NiftiLabelsMasker¶

class nilearn.maskers.NiftiLabelsMasker(labels_img, labels=None, background_label=0, mask_img=None, smoothing_fwhm=None, standardize=False, standardize_confounds=True, high_variance_confounds=False, detrend=False, low_pass=None, high_pass=None, t_r=None, dtype=None, resampling_target='data', memory=None, memory_level=1, verbose=0, strategy='mean', keep_masked_labels=True, reports=True, **kwargs)[source]¶

Class for extracting data from Niimg-like objects using labels of non-overlapping brain regions.

NiftiLabelsMasker is useful when data from non-overlapping volumes should be extracted (contrarily to nilearn.maskers.NiftiMapsMasker).

Use case: summarize brain signals from clusters that were obtained by prior K-means or Ward clustering.

For more details on the definitions of labels in Nilearn, see the Extraction of signals from regions: NiftiLabelsMasker, NiftiMapsMasker section.

Parameters:

labels_imgNiimg-like object

See Input and output: neuroimaging data representation. Region definitions, as one image of labels.

labelslist of str, optional

Full labels corresponding to the labels image. This is used to improve reporting quality if provided.

Warning

The labels must be consistent with the label values provided through labels_img.

background_labelint or float, default=0

Label used in labels_img to represent background.

mask_imgNiimg-like object, optional

See Input and output: neuroimaging data representation. Mask to apply to regions before extracting signals.

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.

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.

resampling_target{“data”, “labels”, None}, default=”data”

Gives which image gives the final shape/size. For example, if resampling_target is "data", the atlas is resampled to the shape of the data if needed. If it is "labels" then mask_img and images provided to fit() are resampled to the shape and affine of maps_img. "None" means no resampling: if shapes and affines do not match, a ValueError is raised.

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

strategystr, default=’mean’

The name of a valid function to reduce the region with. Must be one of: sum, mean, median, minimum, maximum, variance, standard_deviation.

keep_masked_labelsbool, default=True

When a mask is supplied through the “mask_img” parameter, some atlas regions may lie entirely outside of the brain mask, resulting in empty time series for those regions. If True, the masked atlas with these empty labels will be retained in the output, resulting in corresponding time series containing zeros only. If False, the empty labels will be removed from the output, ensuring no empty time series are present.

Deprecated since version 0.10.2: The ‘True’ option for keep_masked_labels is deprecated. The default value will change to ‘False’ in 0.13, and the keep_masked_labels parameter will be removed in 0.15.

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.
labels_img_nibabel.nifti1.Nifti1Image: The labels image.
n_elements_int: The number of discrete values in the mask. This is equivalent to the number of unique values in the mask image, ignoring the background value.

Added in version 0.9.2.
region_ids_dict[str | int, int]: A dictionary containing the region ids corresponding to each column in the region_signal returned by fit_transform. The region id corresponding to region_signal[:,i] is region_ids_[i]. region_ids_['background'] is the background label.

Added in version 0.10.3.
region_names_dict[int, str]: A dictionary containing the region names corresponding to each column in the region_signal returned by fit_transform. The region names correspond to the labels provided in labels in input. The region name corresponding to region_signal[:,i] is region_names_[i].

Added in version 0.10.3.
region_atlas_Niimg-like object: Regions definition as labels. The labels correspond to the indices in region_ids_. The region in region_atlas_ that takes the value region_ids_[i] is used to compute the signal in region_signal[:,i].

Added in version 0.10.3.

Examples using `nilearn.maskers.NiftiLabelsMasker`¶

Extracting signals from a brain parcellation

Comparing connectomes on different reference atlases

Extracting signals from brain regions using the NiftiLabelsMasker

Computing a Region of Interest (ROI) mask manually

nilearn.maskers.NiftiLabelsMasker¶

Examples using nilearn.maskers.NiftiLabelsMasker¶

Examples using `nilearn.maskers.NiftiLabelsMasker`¶