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()

Retrieve the brain development functional dataset

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

from nilearn.datasets import fetch_atlas_harvard_oxford, fetch_development_fmri

dataset = 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}")

[fetch_development_fmri] Dataset found in
/home/runner/nilearn_data/development_fmri
[fetch_development_fmri] Dataset found in
/home/runner/nilearn_data/development_fmri/development_fmri
[fetch_development_fmri] 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 and the first label correspond to the background.

atlas = fetch_atlas_harvard_oxford("cort-maxprob-thr25-2mm")
print(f"The atlas contains {len(atlas.labels) - 1} non-overlapping regions")

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

Instantiate the mask and visualize atlas

Instantiate the masker with label image and label values

from nilearn.maskers import NiftiLabelsMasker

masker = NiftiLabelsMasker(
    atlas.maps, lut=atlas.lut, standardize="zscore_sample", verbose=1
)

Visualize the atlas

Note

We need to call fit prior to generating the mask.

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.

masker.fit()

report = masker.generate_report()
report

[NiftiLabelsMasker.fit] Loading regions from <nibabel.nifti1.Nifti1Image object
at 0x7f8ed47b1d20>
[NiftiLabelsMasker.fit] Finished fit
/home/runner/work/nilearn/nilearn/examples/06_manipulating_images/plot_nifti_labels_simple.py:71: UserWarning: No image provided to fit in NiftiLabelsMasker. Plotting ROIs of label image on the MNI152Template for reporting.
  report = masker.generate_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.40
10	Superior Temporal Gyrus, posterior division	14640	1.40
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.40
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.20
48	Occipital Pole	42208	4.03

	Value
Parameter
background_label	0
clean_args	None
cmap	CMRmap_r
detrend	False
dtype	None
high_pass	None
high_variance_confounds	False
keep_masked_labels	False
labels	None
labels_img	\n<class 'nibabel.nifti1.Nifti1Image'>\ndata shape (91, 109, 91)\naffine:\n[[ 2. 0. 0. -90.]\n [ 0. 2. 0. -126.]\n [ 0. 0. 2. -72.]\n [ 0. 0. 0. 1.]]\nmetadata:\n<class 'nibabel.nifti1.Nifti1Header'> object, endian='<'\nsizeof_hdr : 348\ndata_type : b''\ndb_name : b''\nextents : 0\nsession_error : 0\nregular : b'r'\ndim_info : 0\ndim : [ 3 91 109 91 1 1 1 1]\nintent_p1 : 0.0\nintent_p2 : 0.0\nintent_p3 : 0.0\nintent_code : none\ndatatype : uint8\nbitpix : 8\nslice_start : 0\npixdim : [1. 2. 2. 2. 1. 1. 1. 1.]\nvox_offset : 0.0\nscl_slope : nan\nscl_inter : nan\nslice_end : 0\nslice_code : unknown\nxyzt_units : 10\ncal_max : 48.0\ncal_min : 0.0\nslice_duration : 0.0\ntoffset : 0.0\nglmax : 0\nglmin : 0\ndescrip : b'FSL3.3'\naux_file : b'MGH-Cortical'\nqform_code : unknown\nsform_code : aligned\nquatern_b : 0.0\nquatern_c : 0.0\nquatern_d : 0.0\nqoffset_x : -90.0\nqoffset_y : -126.0\nqoffset_z : -72.0\nsrow_x : [ 2. 0. 0. -90.]\nsrow_y : [ 0. 2. 0. -126.]\nsrow_z : [ 0. 0. 2. -72.]\nintent_name : b''\nmagic : b'n+1'\n
low_pass	None
lut	index name 0 0 Background 1 1 Frontal Pole 2 2 Insular Cortex 3 3 Superior Frontal Gyrus 4 4 Middle Frontal Gyrus 5 5 Inferior Frontal Gyrus, pars triangularis 6 6 Inferior Frontal Gyrus, pars opercularis 7 7 Precentral Gyrus 8 8 Temporal Pole 9 9 Superior Temporal Gyrus, anterior division 10 10 Superior Temporal Gyrus, posterior division 11 11 Middle Temporal Gyrus, anterior division 12 12 Middle Temporal Gyrus, posterior division 13 13 Middle Temporal Gyrus, temporooccipital part 14 14 Inferior Temporal Gyrus, anterior division 15 15 Inferior Temporal Gyrus, posterior division 16 16 Inferior Temporal Gyrus, temporooccipital part 17 17 Postcentral Gyrus 18 18 Superior Parietal Lobule 19 19 Supramarginal Gyrus, anterior division 20 20 Supramarginal Gyrus, posterior division 21 21 Angular Gyrus 22 22 Lateral Occipital Cortex, superior division 23 23 Lateral Occipital Cortex, inferior division 24 24 Intracalcarine Cortex 25 25 Frontal Medial Cortex 26 26 Juxtapositional Lobule Cortex (formerly Supplementary Motor Cortex) 27 27 Subcallosal Cortex 28 28 Paracingulate Gyrus 29 29 Cingulate Gyrus, anterior division 30 30 Cingulate Gyrus, posterior division 31 31 Precuneous Cortex 32 32 Cuneal Cortex 33 33 Frontal Orbital Cortex 34 34 Parahippocampal Gyrus, anterior division 35 35 Parahippocampal Gyrus, posterior division 36 36 Lingual Gyrus 37 37 Temporal Fusiform Cortex, anterior division 38 38 Temporal Fusiform Cortex, posterior division 39 39 Temporal Occipital Fusiform Cortex 40 40 Occipital Fusiform Gyrus 41 41 Frontal Opercular Cortex 42 42 Central Opercular Cortex 43 43 Parietal Opercular Cortex 44 44 Planum Polare 45 45 Heschl's Gyrus (includes H1 and H2) 46 46 Planum Temporale 47 47 Supracalcarine Cortex 48 48 Occipital Pole
mask_img	None
memory	None
memory_level	1
reports	True
resampling_target	data
smoothing_fwhm	None
standardize	zscore_sample
standardize_confounds	True
strategy	mean
t_r	None
verbose	1

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 masker on data and generating a report

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.

masker.fit(func_filename)

report = masker.generate_report()
report

[NiftiLabelsMasker.fit] Loading regions from <nibabel.nifti1.Nifti1Image object
at 0x7f8ed47b1d20>
[NiftiLabelsMasker.fit] Resampling regions
[NiftiLabelsMasker.fit] Finished fit

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	123008	11.76
2	Insular Cortex	18240	1.74
3	Superior Frontal Gyrus	40064	3.83
4	Middle Frontal Gyrus	42048	4.02
5	Inferior Frontal Gyrus, pars triangularis	8576	0.82
6	Inferior Frontal Gyrus, pars opercularis	10880	1.04
7	Precentral Gyrus	68352	6.53
8	Temporal Pole	38016	3.63
9	Superior Temporal Gyrus, anterior division	4160	0.40
10	Superior Temporal Gyrus, posterior division	14272	1.36
11	Middle Temporal Gyrus, anterior division	6528	0.62
12	Middle Temporal Gyrus, posterior division	20224	1.93
13	Middle Temporal Gyrus, temporooccipital part	15680	1.50
14	Inferior Temporal Gyrus, anterior division	5248	0.50
15	Inferior Temporal Gyrus, posterior division	15616	1.49
16	Inferior Temporal Gyrus, temporooccipital part	11648	1.11
17	Postcentral Gyrus	54400	5.20
18	Superior Parietal Lobule	24000	2.29
19	Supramarginal Gyrus, anterior division	14016	1.34
20	Supramarginal Gyrus, posterior division	17600	1.68
21	Angular Gyrus	19328	1.85
22	Lateral Occipital Cortex, superior division	78272	7.48
23	Lateral Occipital Cortex, inferior division	33600	3.21
24	Intracalcarine Cortex	11008	1.05
25	Frontal Medial Cortex	7744	0.74
26	Juxtapositional Lobule Cortex (formerly Supplementary Motor Cortex)	11968	1.14
27	Subcallosal Cortex	8960	0.86
28	Paracingulate Gyrus	23104	2.21
29	Cingulate Gyrus, anterior division	20480	1.96
30	Cingulate Gyrus, posterior division	19392	1.85
31	Precuneous Cortex	44800	4.28
32	Cuneal Cortex	10176	0.97
33	Frontal Orbital Cortex	26240	2.51
34	Parahippocampal Gyrus, anterior division	9728	0.93
35	Parahippocampal Gyrus, posterior division	5760	0.55
36	Lingual Gyrus	26816	2.56
37	Temporal Fusiform Cortex, anterior division	4864	0.47
38	Temporal Fusiform Cortex, posterior division	12224	1.17
39	Temporal Occipital Fusiform Cortex	11904	1.14
40	Occipital Fusiform Gyrus	14336	1.37
41	Frontal Opercular Cortex	5632	0.54
42	Central Opercular Cortex	14976	1.43
43	Parietal Opercular Cortex	9600	0.92
44	Planum Polare	5952	0.57
45	Heschl's Gyrus (includes H1 and H2)	4864	0.47
46	Planum Temporale	7680	0.73
47	Supracalcarine Cortex	1920	0.18
48	Occipital Pole	42112	4.03

	Value
Parameter
background_label	0
clean_args	None
cmap	CMRmap_r
detrend	False
dtype	None
high_pass	None
high_variance_confounds	False
keep_masked_labels	False
labels	None
labels_img	\n<class 'nibabel.nifti1.Nifti1Image'>\ndata shape (91, 109, 91)\naffine:\n[[ 2. 0. 0. -90.]\n [ 0. 2. 0. -126.]\n [ 0. 0. 2. -72.]\n [ 0. 0. 0. 1.]]\nmetadata:\n<class 'nibabel.nifti1.Nifti1Header'> object, endian='<'\nsizeof_hdr : 348\ndata_type : b''\ndb_name : b''\nextents : 0\nsession_error : 0\nregular : b'r'\ndim_info : 0\ndim : [ 3 91 109 91 1 1 1 1]\nintent_p1 : 0.0\nintent_p2 : 0.0\nintent_p3 : 0.0\nintent_code : none\ndatatype : uint8\nbitpix : 8\nslice_start : 0\npixdim : [1. 2. 2. 2. 1. 1. 1. 1.]\nvox_offset : 0.0\nscl_slope : nan\nscl_inter : nan\nslice_end : 0\nslice_code : unknown\nxyzt_units : 10\ncal_max : 48.0\ncal_min : 0.0\nslice_duration : 0.0\ntoffset : 0.0\nglmax : 0\nglmin : 0\ndescrip : b'FSL3.3'\naux_file : b'MGH-Cortical'\nqform_code : unknown\nsform_code : aligned\nquatern_b : 0.0\nquatern_c : 0.0\nquatern_d : 0.0\nqoffset_x : -90.0\nqoffset_y : -126.0\nqoffset_z : -72.0\nsrow_x : [ 2. 0. 0. -90.]\nsrow_y : [ 0. 2. 0. -126.]\nsrow_z : [ 0. 0. 2. -72.]\nintent_name : b''\nmagic : b'n+1'\n
low_pass	None
lut	index name 0 0 Background 1 1 Frontal Pole 2 2 Insular Cortex 3 3 Superior Frontal Gyrus 4 4 Middle Frontal Gyrus 5 5 Inferior Frontal Gyrus, pars triangularis 6 6 Inferior Frontal Gyrus, pars opercularis 7 7 Precentral Gyrus 8 8 Temporal Pole 9 9 Superior Temporal Gyrus, anterior division 10 10 Superior Temporal Gyrus, posterior division 11 11 Middle Temporal Gyrus, anterior division 12 12 Middle Temporal Gyrus, posterior division 13 13 Middle Temporal Gyrus, temporooccipital part 14 14 Inferior Temporal Gyrus, anterior division 15 15 Inferior Temporal Gyrus, posterior division 16 16 Inferior Temporal Gyrus, temporooccipital part 17 17 Postcentral Gyrus 18 18 Superior Parietal Lobule 19 19 Supramarginal Gyrus, anterior division 20 20 Supramarginal Gyrus, posterior division 21 21 Angular Gyrus 22 22 Lateral Occipital Cortex, superior division 23 23 Lateral Occipital Cortex, inferior division 24 24 Intracalcarine Cortex 25 25 Frontal Medial Cortex 26 26 Juxtapositional Lobule Cortex (formerly Supplementary Motor Cortex) 27 27 Subcallosal Cortex 28 28 Paracingulate Gyrus 29 29 Cingulate Gyrus, anterior division 30 30 Cingulate Gyrus, posterior division 31 31 Precuneous Cortex 32 32 Cuneal Cortex 33 33 Frontal Orbital Cortex 34 34 Parahippocampal Gyrus, anterior division 35 35 Parahippocampal Gyrus, posterior division 36 36 Lingual Gyrus 37 37 Temporal Fusiform Cortex, anterior division 38 38 Temporal Fusiform Cortex, posterior division 39 39 Temporal Occipital Fusiform Cortex 40 40 Occipital Fusiform Gyrus 41 41 Frontal Opercular Cortex 42 42 Central Opercular Cortex 43 43 Parietal Opercular Cortex 44 44 Planum Polare 45 45 Heschl's Gyrus (includes H1 and H2) 46 46 Planum Temporale 47 47 Supracalcarine Cortex 48 48 Occipital Pole
mask_img	None
memory	None
memory_level	1
reports	True
resampling_target	data
smoothing_fwhm	None
standardize	zscore_sample
standardize_confounds	True
strategy	mean
t_r	None
verbose	1

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 numpy array, (n_time_points x n_regions)
print(f"{signals.shape=}")

[NiftiLabelsMasker.wrapped] Loading data from
'/home/runner/nilearn_data/development_fmri/development_fmri/sub-pixar123_task-p
ixar_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz'
[NiftiLabelsMasker.wrapped] Extracting region signals
[NiftiLabelsMasker.wrapped] Cleaning extracted signals
signals.shape=(168, 48)

Output to dataframe and plot

You can use ‘set_output()’ to decide the output format of ‘transform’. If you want to output to a DataFrame, you an choose pandas and polars.

masker.set_output(transform="pandas")
signals_df = masker.transform(func_filename)
print(signals_df.head)

signals_df[["Frontal Pole", "Insular Cortex", "Superior Frontal Gyrus"]].plot(
    title="Signals from 3 regions", figsize=(15, 5)
)

[NiftiLabelsMasker.wrapped] Loading data from
'/home/runner/nilearn_data/development_fmri/development_fmri/sub-pixar123_task-p
ixar_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz'
[NiftiLabelsMasker.wrapped] Extracting region signals
[NiftiLabelsMasker.wrapped] Cleaning extracted signals
<bound method NDFrame.head of      Frontal Pole  Insular Cortex  ...  Supracalcarine Cortex  Occipital Pole
0       -0.446359       -1.225659  ...              -3.582685       -2.001927
1       -0.715557       -1.626162  ...              -2.323499       -2.348940
2       -1.508380       -2.026665  ...              -1.190231       -2.087385
3       -0.956851       -1.190833  ...              -0.371760       -2.600137
4       -1.106224       -1.121180  ...              -0.686556       -2.732209
..            ...             ...  ...                    ...             ...
163      1.142570        1.769406  ...               0.950386        0.844104
164      1.726928        2.883849  ...               1.705898        0.191511
165      1.653063        0.968400  ...               2.839166        0.346890
166      1.216436        0.028089  ...               2.335491       -0.189168
167      0.993198        0.358939  ...               0.635589       -0.310882

[168 rows x 48 columns]>

<Axes: title={'center': 'Signals from 3 regions'}>

Estimated memory usage: 667 MB