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

class nilearn.maskers.MultiNiftiLabelsMasker(labels_img=None, labels=None, lut=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, n_jobs=1, clean_args=None, **kwargs)[source]¶

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

MultiNiftiLabelsMasker is useful when data from non-overlapping volumes and from different subjects should be extracted (contrary to nilearn.maskers.NiftiLabelsMasker).

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 or None, default=None

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.

lutpandas.DataFrame or str or pathlib.Path to a TSV file or None, default=None

Mutually exclusive with labels. Act as a look up table (lut) with at least columns ‘index’ and ‘name’. Formatted according to ‘dseg.tsv’ format from BIDS.

background_labelint or float, default=0

Label used in labels_img to represent background.

Warning

This value must be consistent with label values and image provided.

mask_imgNiimg-like object, optional

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

smoothing_fwhmfloat or int or None, 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 int 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 or int or None, default=None

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

t_rfloat or int or None, default=None

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

dtypedtype like, “auto” or None, default=None

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:

“data” means the atlas is resampled to the shape of the data if needed

“labels” means en 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.

n_jobsint, default=1

The number of CPUs to use to do the computation. -1 means ‘all CPUs’.

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.

clean_argsdict or None, default=None

Keyword arguments to be passed to clean called within the masker. Within clean, kwargs prefixed with 'butterworth__' will be passed to the Butterworth filter.

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

Deprecated since version 0.11.2dev.

Use clean_args instead!

It is recommended to pass parameters to use for data cleaning via dict to the clean_args parameter.

Passing parameters via “kwargs” is mutually exclusive with passing cleaning parameters via clean_args.

Attributes:

mask_img_A 3D binary nibabel.nifti1.Nifti1Image or None.: The mask of the data. If no mask_img was passed at masker construction, then mask_img_ is None, otherwise is the resulting binarized version of mask_img where each voxel is True if all values across samples (for example across timepoints) is finite value different from 0.
labels_img_nibabel.nifti1.Nifti1Image: The labels image.

Examples using `nilearn.maskers.MultiNiftiLabelsMasker`¶

Comparing connectomes on different reference atlases

nilearn.maskers.MultiNiftiLabelsMasker¶

Examples using nilearn.maskers.MultiNiftiLabelsMasker¶

Examples using `nilearn.maskers.MultiNiftiLabelsMasker`¶