Note

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

nilearn.regions.img_to_signals_labels¶

nilearn.regions.img_to_signals_labels(imgs, labels_img, mask_img=None, background_label=0, order='F', strategy='mean', keep_masked_labels=True, return_masked_atlas=False)[source]¶

Extract region signals from image.

This function is applicable to regions defined by labels.

labels, imgs and mask shapes and affines must fit. This function performs no resampling.

Parameters:

imgslist of Niimg-like objects: See Input and output: neuroimaging data representation. Input images.
labels_imgNiimg-like object: See Input and output: neuroimaging data representation. Regions definition as labels. By default, the label zero is used to denote an absence of region. Use background_label to change it.
mask_imgNiimg-like object, optional: See Input and output: neuroimaging data representation. Mask to apply to labels before extracting signals. Every point outside the mask is considered as background (i.e. no region).
background_labelnumber, default=0: Number representing background in labels_img.
orderstr, default=”F”: Ordering of output array (“C” or “F”).
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.
return_masked_atlasbool, default=False: If True, the masked atlas is returned. deprecated in version 0.13, to be removed in 0.15. after 0.13, the masked atlas will always be returned.

Returns:

signalsnumpy.ndarray: Signals extracted from each region. One output signal is the mean of all input signals in a given region. If some regions are entirely outside the mask, the corresponding signal is zero. Shape is: (scan number, number of regions)
labelslist or tuple: Corresponding labels for each signal. signal[:, n] was extracted from the region with label labels[n].
masked_atlasNiimg-like object: Regions definition as labels after applying the mask. returned if return_masked_atlas is True.