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

nilearn.regions.signals_to_img_labels(signals, labels_img, mask_img=None, background_label=0, order='F')

Create image from region signals defined as labels.

The same region signal is used for each voxel of the corresponding 3D volume.

labels_img, mask_img must have the same shapes and affines.

Changed in Nilearn 0.9.2: Support 1D signals.

Parameters:

signalsnumpy.ndarray

1D or 2D array. If this is a 1D array, it must have as many elements as there are regions in the labels_img. If it is 2D, it should have the shape (number of scans, number of regions in labels_img).

labels_imgNiimg-like object

See Input and output: neuroimaging data representation. Region definitions using labels.

mask_imgNiimg-like object, default=None

See Input and output: neuroimaging data representation. Boolean array giving voxels to process. integer arrays also accepted, In this array, zero means False, non-zero means True.

background_labelnumber, default=0

Label to use for “no region”.

orderstr, default=’F’

Ordering of output array (“C” or “F”).

Returns:

imgnibabel.nifti1.Nifti1Image

Reconstructed image. dtype is that of “signals”, affine and shape are those of labels_img.

See also

nilearn.regions.img_to_signals_labels

nilearn.regions.signals_to_img_maps

nilearn.maskers.NiftiLabelsMasker

Signal extraction on labels images e.g. clusters

Examples

>>> import numpy as np
>>> from nilearn.regions import signals_to_img_labels
>>>
>>> # create signals with 2 time points and 3 regions
>>> signals = np.random.default_rng(42).standard_normal((2, 3))
>>> signals
array([[ 0.30471708, -1.03998411,  0.7504512 ],
       [ 0.94056472, -1.95103519, -1.30217951]])
>>>
>>> # create labels 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 image from region signals defined as labels
>>> img = signals_to_img_labels(signals, labels_img)
>>> img_data = img.get_fdata()
>>> img_data
array([[[[ 0.30471708,  0.94056472],
         [-1.03998411, -1.95103519]],
        [[ 0.30471708,  0.94056472],
         [-1.03998411, -1.95103519]]],
       [[[ 0.7504512 , -1.30217951],
         [ 0.7504512 , -1.30217951]],
        [[ 0.7504512 , -1.30217951],
         [ 0.7504512 , -1.30217951]]]])