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.

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

Visualize the atlas

We need to call fit prior to generating the mask. We can then generate a report to visualize the atlas.

Note

The generated report can be:

• displayed in a 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 0x7f32a80adf00>
[NiftiLabelsMasker.fit] Finished fit
/home/runner/work/nilearn/nilearn/examples/06_manipulating_images/plot_nifti_labels_simple.py:64: 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.

WARNING

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

This report 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

NiftiLabelsMasker(labels_img=<nibabel.nifti1.Nifti1Image object at 0x7f32a80adf00>,
                  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, p...
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,
                  verbose=1)

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

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 0x7f32a80adf00>
[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 report 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

NiftiLabelsMasker(labels_img=<nibabel.nifti1.Nifti1Image object at 0x7f32a80adf00>,
                  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, p...
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,
                  verbose=1)

In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook.
On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.

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

/home/runner/work/nilearn/nilearn/examples/06_manipulating_images/plot_nifti_labels_simple.py:86: FutureWarning:

boolean values for 'standardize' will be deprecated in nilearn 0.15.0.
Use 'zscore_sample' instead of 'True' or use 'None' instead of 'False'.

[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
/home/runner/work/nilearn/nilearn/examples/06_manipulating_images/plot_nifti_labels_simple.py:86: FutureWarning:

boolean values for 'standardize' will be deprecated in nilearn 0.15.0.
Use 'zscore_sample' instead of 'True' or use 'None' instead of 'False'.

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

/home/runner/work/nilearn/nilearn/examples/06_manipulating_images/plot_nifti_labels_simple.py:99: FutureWarning:

boolean values for 'standardize' will be deprecated in nilearn 0.15.0.
Use 'zscore_sample' instead of 'True' or use 'None' instead of 'False'.

[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
/home/runner/work/nilearn/nilearn/examples/06_manipulating_images/plot_nifti_labels_simple.py:99: FutureWarning:

boolean values for 'standardize' will be deprecated in nilearn 0.15.0.
Use 'zscore_sample' instead of 'True' or use 'None' instead of 'False'.

<bound method NDFrame.head of      Frontal Pole  Insular Cortex  ...  Supracalcarine Cortex  Occipital Pole
0      635.218164      555.308283  ...             559.291453      681.952471
1      634.725215      554.842059  ...             563.142865      680.775976
2      633.273421      554.375836  ...             566.609135      681.662737
3      634.283365      555.348824  ...             569.112553      679.924334
4      634.009838      555.429906  ...             568.149700      679.476564
..            ...             ...  ...                    ...             ...
163    638.127763      558.794824  ...             573.156535      691.601486
164    639.197822      560.092141  ...             575.467382      689.388973
165    639.062562      557.862377  ...             578.933652      689.915762
166    638.263023      556.767765  ...             577.393087      688.098340
167    637.854236      557.152906  ...             572.193682      687.685689

[168 rows x 48 columns]>

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

Estimated memory usage: 296 MB