Extracting signals from brain regions using the NiftiLabelsMasker

This simple example shows how to extract signals from functional fMRI data and brain regions defined through an atlas. More precisely, this example shows how to use the NiftiLabelsMasker object to perform this operation in just a few lines of code.

Note

If you are using Nilearn with a version older than 0.9.0, then you should either upgrade your version or import maskers from the input_data module instead of the maskers module.

That is, you should manually replace in the following example all occurrences of:

from nilearn.maskers import NiftiMasker

with:

from nilearn.input_data import NiftiMasker

from nilearn._utils.helpers import check_matplotlib

check_matplotlib()

import matplotlib.pyplot as plt

from nilearn import datasets

Retrieve the brain development functional dataset

We start by fetching the brain development functional dataset and we restrict the example to one subject only.

dataset = datasets.fetch_development_fmri(n_subjects=1)
func_filename = dataset.func[0]

# print basic information on the dataset
print(f"First functional nifti image (4D) is at: {func_filename}")

[get_dataset_dir] Dataset found in /home/runner/nilearn_data/development_fmri
[get_dataset_dir] Dataset found in
/home/runner/nilearn_data/development_fmri/development_fmri
[get_dataset_dir] Dataset found in
/home/runner/nilearn_data/development_fmri/development_fmri
First functional nifti image (4D) is at: /home/runner/nilearn_data/development_fmri/development_fmri/sub-pixar123_task-pixar_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz

Load an atlas

We then load the Harvard-Oxford atlas to define the brain regions

atlas = datasets.fetch_atlas_harvard_oxford("cort-maxprob-thr25-2mm")

# The first label correspond to the background
print(f"The atlas contains {len(atlas.labels) - 1} non-overlapping regions")

[get_dataset_dir] Dataset found in /home/runner/nilearn_data/fsl
The atlas contains 48 non-overlapping regions

Instantiate the mask and visualize atlas

from nilearn.maskers import NiftiLabelsMasker

# Instantiate the masker with label image and label values
masker = NiftiLabelsMasker(
    atlas.maps,
    labels=atlas.labels,
    standardize="zscore_sample",
)

# Visualize the atlas
# Note that we need to call fit prior to generating the mask
masker.fit()

# At this point, no functional image has been provided to the masker.
# We can still generate a report which can be displayed in a Jupyter
# Notebook, opened in a browser using the .open_in_browser() method,
# or saved to a file using the .save_as_html(output_filepath) method.
report = masker.generate_report()
report

/home/runner/work/nilearn/nilearn/examples/06_manipulating_images/plot_nifti_labels_simple.py:65: UserWarning:

No image provided to fit in NiftiLabelsMasker. Plotting ROIs of label image on the MNI152Template for reporting.

NiftiLabelsMasker 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 :class:`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 :ref:`region` section.

This reports shows the regions defined by the labels of the mask.

The masker has 48 different non-overlapping regions.

Regions summary

label value	region name	size (in mm^3)	relative size (in %)
1	Frontal Pole	123176	11.75
2	Insular Cortex	18728	1.79
3	Superior Frontal Gyrus	40640	3.88
4	Middle Frontal Gyrus	42528	4.06
5	Inferior Frontal Gyrus, pars triangularis	8824	0.84
6	Inferior Frontal Gyrus, pars opercularis	11072	1.06
7	Precentral Gyrus	68584	6.54
8	Temporal Pole	37688	3.59
9	Superior Temporal Gyrus, anterior division	4168	0.4
10	Superior Temporal Gyrus, posterior division	14640	1.4
11	Middle Temporal Gyrus, anterior division	6784	0.65
12	Middle Temporal Gyrus, posterior division	20200	1.93
13	Middle Temporal Gyrus, temporooccipital part	16032	1.53
14	Inferior Temporal Gyrus, anterior division	5176	0.49
15	Inferior Temporal Gyrus, posterior division	15536	1.48
16	Inferior Temporal Gyrus, temporooccipital part	11760	1.12
17	Postcentral Gyrus	55160	5.26
18	Superior Parietal Lobule	23264	2.22
19	Supramarginal Gyrus, anterior division	13936	1.33
20	Supramarginal Gyrus, posterior division	18072	1.72
21	Angular Gyrus	19272	1.84
22	Lateral Occipital Cortex, superior division	78232	7.46
23	Lateral Occipital Cortex, inferior division	32712	3.12
24	Intracalcarine Cortex	11208	1.07
25	Frontal Medial Cortex	7808	0.74
26	Juxtapositional Lobule Cortex (formerly Supplementary Motor Cortex)	11872	1.13
27	Subcallosal Cortex	9136	0.87
28	Paracingulate Gyrus	23552	2.25
29	Cingulate Gyrus, anterior division	20736	1.98
30	Cingulate Gyrus, posterior division	19296	1.84
31	Precuneous Cortex	44984	4.29
32	Cuneal Cortex	9816	0.94
33	Frontal Orbital Cortex	25184	2.4
34	Parahippocampal Gyrus, anterior division	9984	0.95
35	Parahippocampal Gyrus, posterior division	5680	0.54
36	Lingual Gyrus	27048	2.58
37	Temporal Fusiform Cortex, anterior division	4880	0.47
38	Temporal Fusiform Cortex, posterior division	12752	1.22
39	Temporal Occipital Fusiform Cortex	11752	1.12
40	Occipital Fusiform Gyrus	14448	1.38
41	Frontal Opercular Cortex	5496	0.52
42	Central Opercular Cortex	15088	1.44
43	Parietal Opercular Cortex	8952	0.85
44	Planum Polare	5992	0.57
45	Heschl's Gyrus (includes H1 and H2)	4832	0.46
46	Planum Temporale	7616	0.73
47	Supracalcarine Cortex	2088	0.2
48	Occipital Pole	42208	4.03

Parameters

Parameter	Value
background_label	0
detrend	False
dtype	None
high_pass	None
high_variance_confounds	False
keep_masked_labels	True
labels	['Background', 'Frontal Pole', 'Insular Cortex', 'Superior Frontal Gyrus', 'Middle Frontal Gyrus', 'Inferior Frontal Gyrus, pars triangularis', 'Inferior Frontal Gyrus, pars opercularis', 'Precentral Gyrus', 'Temporal Pole', 'Superior Temporal Gyrus, anterior division', 'Superior Temporal Gyrus, posterior division', 'Middle Temporal Gyrus, anterior division', 'Middle Temporal Gyrus, posterior division', 'Middle Temporal Gyrus, temporooccipital part', 'Inferior Temporal Gyrus, anterior division', 'Inferior Temporal Gyrus, posterior division', 'Inferior Temporal Gyrus, temporooccipital part', 'Postcentral Gyrus', 'Superior Parietal Lobule', 'Supramarginal Gyrus, anterior division', 'Supramarginal Gyrus, posterior division', 'Angular Gyrus', 'Lateral Occipital Cortex, superior division', 'Lateral Occipital Cortex, inferior division', 'Intracalcarine Cortex', 'Frontal Medial Cortex', 'Juxtapositional Lobule Cortex (formerly Supplementary Motor Cortex)', 'Subcallosal Cortex', 'Paracingulate Gyrus', 'Cingulate Gyrus, anterior division', 'Cingulate Gyrus, posterior division', 'Precuneous Cortex', 'Cuneal Cortex', 'Frontal Orbital Cortex', 'Parahippocampal Gyrus, anterior division', 'Parahippocampal Gyrus, posterior division', 'Lingual Gyrus', 'Temporal Fusiform Cortex, anterior division', 'Temporal Fusiform Cortex, posterior division', 'Temporal Occipital Fusiform Cortex', 'Occipital Fusiform Gyrus', 'Frontal Opercular Cortex', 'Central Opercular Cortex', 'Parietal Opercular Cortex', 'Planum Polare', "Heschl's Gyrus (includes H1 and H2)", 'Planum Temporale', 'Supracalcarine Cortex', 'Occipital Pole']
labels_img	<class 'nibabel.nifti1.Nifti1Image'> data shape (91, 109, 91) affine: [[ 2. 0. 0. -90.] [ 0. 2. 0. -126.] [ 0. 0. 2. -72.] [ 0. 0. 0. 1.]] metadata: <class 'nibabel.nifti1.Nifti1Header'> object, endian='<' sizeof_hdr : 348 data_type : b'' db_name : b'' extents : 0 session_error : 0 regular : b'r' dim_info : 0 dim : [ 3 91 109 91 1 1 1 1] intent_p1 : 0.0 intent_p2 : 0.0 intent_p3 : 0.0 intent_code : none datatype : uint8 bitpix : 8 slice_start : 0 pixdim : [1. 2. 2. 2. 1. 1. 1. 1.] vox_offset : 0.0 scl_slope : nan scl_inter : nan slice_end : 0 slice_code : unknown xyzt_units : 10 cal_max : 48.0 cal_min : 0.0 slice_duration : 0.0 toffset : 0.0 glmax : 0 glmin : 0 descrip : b'FSL3.3' aux_file : b'MGH-Cortical' qform_code : unknown sform_code : aligned quatern_b : 0.0 quatern_c : 0.0 quatern_d : 0.0 qoffset_x : -90.0 qoffset_y : -126.0 qoffset_z : -72.0 srow_x : [ 2. 0. 0. -90.] srow_y : [ 0. 2. 0. -126.] srow_z : [ 0. 0. 2. -72.] intent_name : b'' magic : b'n+1'
low_pass	None
mask_img	None
memory	Memory(location=None)
memory_level	1
reports	True
resampling_target	data
smoothing_fwhm	None
standardize	zscore_sample
standardize_confounds	True
strategy	mean
t_r	None
verbose	0

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

Fitting the mask and generating a report

masker.fit(func_filename)

# We can again generate a report, but this time, the provided functional
# image is displayed with the ROI of the atlas.
# The report also contains a summary table giving the region sizes in mm3
report = masker.generate_report()
report

NiftiLabelsMasker 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 :class:`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 :ref:`region` section.

This reports shows the regions defined by the labels of the mask.

The masker has 48 different non-overlapping regions.

Regions summary

label value	region name	size (in mm^3)	relative size (in %)
1	Frontal Pole	123176	11.75
2	Insular Cortex	18728	1.79
3	Superior Frontal Gyrus	40640	3.88
4	Middle Frontal Gyrus	42528	4.06
5	Inferior Frontal Gyrus, pars triangularis	8824	0.84
6	Inferior Frontal Gyrus, pars opercularis	11072	1.06
7	Precentral Gyrus	68584	6.54
8	Temporal Pole	37688	3.59
9	Superior Temporal Gyrus, anterior division	4168	0.4
10	Superior Temporal Gyrus, posterior division	14640	1.4
11	Middle Temporal Gyrus, anterior division	6784	0.65
12	Middle Temporal Gyrus, posterior division	20200	1.93
13	Middle Temporal Gyrus, temporooccipital part	16032	1.53
14	Inferior Temporal Gyrus, anterior division	5176	0.49
15	Inferior Temporal Gyrus, posterior division	15536	1.48
16	Inferior Temporal Gyrus, temporooccipital part	11760	1.12
17	Postcentral Gyrus	55160	5.26
18	Superior Parietal Lobule	23264	2.22
19	Supramarginal Gyrus, anterior division	13936	1.33
20	Supramarginal Gyrus, posterior division	18072	1.72
21	Angular Gyrus	19272	1.84
22	Lateral Occipital Cortex, superior division	78232	7.46
23	Lateral Occipital Cortex, inferior division	32712	3.12
24	Intracalcarine Cortex	11208	1.07
25	Frontal Medial Cortex	7808	0.74
26	Juxtapositional Lobule Cortex (formerly Supplementary Motor Cortex)	11872	1.13
27	Subcallosal Cortex	9136	0.87
28	Paracingulate Gyrus	23552	2.25
29	Cingulate Gyrus, anterior division	20736	1.98
30	Cingulate Gyrus, posterior division	19296	1.84
31	Precuneous Cortex	44984	4.29
32	Cuneal Cortex	9816	0.94
33	Frontal Orbital Cortex	25184	2.4
34	Parahippocampal Gyrus, anterior division	9984	0.95
35	Parahippocampal Gyrus, posterior division	5680	0.54
36	Lingual Gyrus	27048	2.58
37	Temporal Fusiform Cortex, anterior division	4880	0.47
38	Temporal Fusiform Cortex, posterior division	12752	1.22
39	Temporal Occipital Fusiform Cortex	11752	1.12
40	Occipital Fusiform Gyrus	14448	1.38
41	Frontal Opercular Cortex	5496	0.52
42	Central Opercular Cortex	15088	1.44
43	Parietal Opercular Cortex	8952	0.85
44	Planum Polare	5992	0.57
45	Heschl's Gyrus (includes H1 and H2)	4832	0.46
46	Planum Temporale	7616	0.73
47	Supracalcarine Cortex	2088	0.2
48	Occipital Pole	42208	4.03

Parameters

Parameter	Value
background_label	0
detrend	False
dtype	None
high_pass	None
high_variance_confounds	False
keep_masked_labels	True
labels	['Background', 'Frontal Pole', 'Insular Cortex', 'Superior Frontal Gyrus', 'Middle Frontal Gyrus', 'Inferior Frontal Gyrus, pars triangularis', 'Inferior Frontal Gyrus, pars opercularis', 'Precentral Gyrus', 'Temporal Pole', 'Superior Temporal Gyrus, anterior division', 'Superior Temporal Gyrus, posterior division', 'Middle Temporal Gyrus, anterior division', 'Middle Temporal Gyrus, posterior division', 'Middle Temporal Gyrus, temporooccipital part', 'Inferior Temporal Gyrus, anterior division', 'Inferior Temporal Gyrus, posterior division', 'Inferior Temporal Gyrus, temporooccipital part', 'Postcentral Gyrus', 'Superior Parietal Lobule', 'Supramarginal Gyrus, anterior division', 'Supramarginal Gyrus, posterior division', 'Angular Gyrus', 'Lateral Occipital Cortex, superior division', 'Lateral Occipital Cortex, inferior division', 'Intracalcarine Cortex', 'Frontal Medial Cortex', 'Juxtapositional Lobule Cortex (formerly Supplementary Motor Cortex)', 'Subcallosal Cortex', 'Paracingulate Gyrus', 'Cingulate Gyrus, anterior division', 'Cingulate Gyrus, posterior division', 'Precuneous Cortex', 'Cuneal Cortex', 'Frontal Orbital Cortex', 'Parahippocampal Gyrus, anterior division', 'Parahippocampal Gyrus, posterior division', 'Lingual Gyrus', 'Temporal Fusiform Cortex, anterior division', 'Temporal Fusiform Cortex, posterior division', 'Temporal Occipital Fusiform Cortex', 'Occipital Fusiform Gyrus', 'Frontal Opercular Cortex', 'Central Opercular Cortex', 'Parietal Opercular Cortex', 'Planum Polare', "Heschl's Gyrus (includes H1 and H2)", 'Planum Temporale', 'Supracalcarine Cortex', 'Occipital Pole']
labels_img	<class 'nibabel.nifti1.Nifti1Image'> data shape (91, 109, 91) affine: [[ 2. 0. 0. -90.] [ 0. 2. 0. -126.] [ 0. 0. 2. -72.] [ 0. 0. 0. 1.]] metadata: <class 'nibabel.nifti1.Nifti1Header'> object, endian='<' sizeof_hdr : 348 data_type : b'' db_name : b'' extents : 0 session_error : 0 regular : b'r' dim_info : 0 dim : [ 3 91 109 91 1 1 1 1] intent_p1 : 0.0 intent_p2 : 0.0 intent_p3 : 0.0 intent_code : none datatype : uint8 bitpix : 8 slice_start : 0 pixdim : [1. 2. 2. 2. 1. 1. 1. 1.] vox_offset : 0.0 scl_slope : nan scl_inter : nan slice_end : 0 slice_code : unknown xyzt_units : 10 cal_max : 48.0 cal_min : 0.0 slice_duration : 0.0 toffset : 0.0 glmax : 0 glmin : 0 descrip : b'FSL3.3' aux_file : b'MGH-Cortical' qform_code : unknown sform_code : aligned quatern_b : 0.0 quatern_c : 0.0 quatern_d : 0.0 qoffset_x : -90.0 qoffset_y : -126.0 qoffset_z : -72.0 srow_x : [ 2. 0. 0. -90.] srow_y : [ 0. 2. 0. -126.] srow_z : [ 0. 0. 2. -72.] intent_name : b'' magic : b'n+1'
low_pass	None
mask_img	None
memory	Memory(location=None)
memory_level	1
reports	True
resampling_target	data
smoothing_fwhm	None
standardize	zscore_sample
standardize_confounds	True
strategy	mean
t_r	None
verbose	0

This report was generated based on information provided at instantiation and fit time. Note that the masker can potentially perform resampling at transform time.

Process the data with the NiftiLablesMasker

In order to extract the signals, we need to call transform on the functional data

signals = masker.transform(func_filename)
# signals is a 2D matrix, (n_time_points x n_regions)
signals.shape

(168, 48)

Plot the signals

fig = plt.figure(figsize=(15, 5))
ax = fig.add_subplot(111)
for label_idx in range(3):
    ax.plot(
        signals[:, label_idx], linewidth=2, label=atlas.labels[label_idx + 1]
    )  # 0 is background
ax.legend(loc=2)
ax.set_title("Signals for first 3 regions")
plt.show()

Estimated memory usage: 714 MB