Extracting signals of a probabilistic atlas of functional regions#

This example extracts the signal on regions defined via a probabilistic atlas, to construct a functional connectome.

We use the MSDL atlas of functional regions in movie-watching.

The key to extract signals is to use the nilearn.maskers.NiftiMapsMasker that can transform nifti objects to time series using a probabilistic atlas.

As the MSDL atlas comes with (x, y, z) MNI coordinates for the different regions, we can visualize the matrix as a graph of interaction in a brain. To avoid having too dense a graph, we represent only the 20% edges with the highest values.


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


from nilearn.input_data import NiftiMasker

Retrieve the atlas and the data#

from nilearn import datasets
atlas = datasets.fetch_atlas_msdl()
# Loading atlas image stored in 'maps'
atlas_filename = atlas['maps']
# Loading atlas data stored in 'labels'
labels = atlas['labels']

# Load the functional datasets
data = datasets.fetch_development_fmri(n_subjects=1)

print('First subject resting-state nifti image (4D) is located at: %s' %
First subject resting-state nifti image (4D) is located at: /home/runner/work/nilearn/nilearn/nilearn_data/development_fmri/development_fmri/sub-pixar123_task-pixar_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz

Extract the time series#

from nilearn.maskers import NiftiMapsMasker
masker = NiftiMapsMasker(maps_img=atlas_filename, standardize=True,
                         memory='nilearn_cache', verbose=5)
time_series = masker.transform(data.func[0],
[NiftiMapsMasker.fit] loading regions from /home/runner/work/nilearn/nilearn/nilearn_data/msdl_atlas/MSDL_rois/msdl_rois.nii
Resampling maps
/usr/share/miniconda3/envs/testenv/lib/python3.9/site-packages/nilearn/_utils/cache_mixin.py:223: UserWarning:

memory_level is currently set to 0 but a Memory object has been provided. Setting memory_level to 1.

[Memory] Calling nilearn.image.resampling.resample_img...
resample_img(<nibabel.nifti1.Nifti1Image object at 0x7fd08eebd4c0>, interpolation='continuous', target_shape=(50, 59, 50), target_affine=array([[   4.,    0.,    0.,  -96.],
       [   0.,    4.,    0., -132.],
       [   0.,    0.,    4.,  -78.],
       [   0.,    0.,    0.,    1.]]))
_____________________________________________________resample_img - 1.3s, 0.0min
[Memory] Calling nilearn.maskers.base_masker._filter_and_extract...
<nilearn.maskers.nifti_maps_masker._ExtractionFunctor object at 0x7fd08eebd550>, { 'allow_overlap': True,
  'detrend': False,
  'dtype': None,
  'high_pass': None,
  'high_variance_confounds': False,
  'low_pass': None,
  'maps_img': '/home/runner/work/nilearn/nilearn/nilearn_data/msdl_atlas/MSDL_rois/msdl_rois.nii',
  'mask_img': None,
  'reports': True,
  'smoothing_fwhm': None,
  'standardize': True,
  'standardize_confounds': True,
  't_r': None,
  'target_affine': None,
  'target_shape': None}, confounds=[ '/home/runner/work/nilearn/nilearn/nilearn_data/development_fmri/development_fmri/sub-pixar123_task-pixar_desc-reducedConfounds_regressors.tsv'], sample_mask=None, dtype=None, memory=Memory(location=nilearn_cache/joblib), memory_level=1, verbose=5)
[NiftiMapsMasker.transform_single_imgs] Loading data from /home/runner/work/nilearn/nilearn/nilearn_data/development_fmri/development_fmri/sub-pixar123_task-pixar_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
[NiftiMapsMasker.transform_single_imgs] Extracting region signals
[NiftiMapsMasker.transform_single_imgs] Cleaning extracted signals
_______________________________________________filter_and_extract - 4.0s, 0.1min

We can generate an HTML report and visualize the components of the NiftiMapsMasker. You can pass the indices of the spatial maps you want to include in the report in the order you want them to appear. Here, we only include maps 2, 6, 7, 16, and 21 in the report:

report = masker.generate_report(displayed_maps=[2, 6, 7, 16, 21])
/usr/share/miniconda3/envs/testenv/lib/python3.9/site-packages/numpy/ma/core.py:2826: UserWarning:

Warning: converting a masked element to nan.

NiftiMapsMasker Class for masking of Niimg-like objects. NiftiMapsMasker is useful when data from overlapping volumes should be extracted (contrarily to :class:`nilearn.maskers.NiftiLabelsMasker`). Use case: Summarize brain signals from large-scale networks obtained by prior PCA or :term:`ICA`. Note that, Inf or NaN present in the given input images are automatically put to zero rather than considered as missing data.



This reports shows the spatial maps provided to the mask.

The masker has 39 spatial maps in total.

Only 5 spatial maps are shown in this report.

Parameter Value
allow_overlap True
detrend False
dtype None
high_pass None
high_variance_confounds False
low_pass None
maps_img /home/runner/work/nilearn/nilearn/nilearn_data/msdl_atlas/MSDL_rois/msdl_rois.nii
mask_img None
memory Memory(location=nilearn_cache/joblib)
memory_level 1
reports True
resampling_target data
smoothing_fwhm None
standardize True
standardize_confounds True
t_r None
verbose 5

time_series is now a 2D matrix, of shape (number of time points x number of regions)

(168, 39)

Build and display a correlation matrix#

from nilearn.connectome import ConnectivityMeasure
correlation_measure = ConnectivityMeasure(kind='correlation')
correlation_matrix = correlation_measure.fit_transform([time_series])[0]

# Display the correlation matrix
import numpy as np
from nilearn import plotting
# Mask out the major diagonal
np.fill_diagonal(correlation_matrix, 0)
plotting.plot_matrix(correlation_matrix, labels=labels, colorbar=True,
                     vmax=0.8, vmin=-0.8)
plot probabilistic atlas extraction
<matplotlib.image.AxesImage object at 0x7fd08e36eeb0>

And now display the corresponding graph#

from nilearn import plotting
coords = atlas.region_coords

# We threshold to keep only the 20% of edges with the highest value
# because the graph is very dense
plotting.plot_connectome(correlation_matrix, coords,
                         edge_threshold="80%", colorbar=True)

plot probabilistic atlas extraction

3D visualization in a web browser#

An alternative to nilearn.plotting.plot_connectome is to use nilearn.plotting.view_connectome that gives more interactive visualizations in a web browser. See 3D Plots of connectomes for more details.

view = plotting.view_connectome(correlation_matrix, coords, edge_threshold='80%')

# In a Jupyter notebook, if ``view`` is the output of a cell, it will
# be displayed below the cell