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', n_jobs=1)

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

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.

n_jobsint, default=1

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

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_atlasnibabel.nifti1.Nifti1Image

Regions definition as labels after applying the mask. If no mask_img has been passed, then this will be the same as the input labels_img.

See also

nilearn.regions.signals_to_img_labels

nilearn.regions.img_to_signals_maps

nilearn.maskers.NiftiLabelsMasker

Signal extraction on labels images e.g. clusters

Examples

Try it in your browser!

>>> import numpy as np
>>> from nibabel import Nifti1Image
>>> from nilearn.regions.signal_extraction import img_to_signals_labels
>>>
>>> # Create a label image with definitions for 3 regions.
>>> labels_data = np.array(
...     [[[1, 2], [1, 2]], [[3, 3], [3, 3]]], dtype=np.int32
... )
>>> labels_img = Nifti1Image(labels_data, np.eye(4))
>>>
>>> # Create data where the average values of regions 1, 2, 3
>>> # is 0, 1 and 2 respectively.
>>> img_data = np.asarray(
...     [
...         [[[0.3], [0.1]], [[-0.3], [1.9]]],
...         [[[2.0], [2.0]], [[2.0], [2.0]]],
...     ]
... )
>>> img = Nifti1Image(img_data, np.eye(4))
>>>
>>> # Extract mean region signals from the image.
>>> mean_signals, _, _ = img_to_signals_labels(img, labels_img)
>>> mean_signals
array([[0., 1., 2.]])
>>>
>>> # We could also extract some other statistics
>>> # (like the maximum) from each region.
>>> maximum_signals, _, _ = img_to_signals_labels(
...     img, labels_img, strategy="maximum"
... )
>>> maximum_signals
array([[0.3, 1.9, 2. ]])

Go BackOpen In Tab