.. _functional_connectomes: ======================================================== Extracting times series to build a functional connectome ======================================================== .. topic:: **Page summary** A *functional connectome* is a set of connections representing brain interactions between regions. Here we show how to extract activation time-series to compute functional connectomes. .. topic:: **References** * Learning and comparing functional connectomes across subjects :footcite:p:`Varoquaux2013` .. _parcellation_time_series: Time-series from a brain parcellation or "MaxProb" atlas ======================================================== Brain parcellations ------------------- .. currentmodule:: nilearn.datasets Regions used to extract the signal can be defined by a "hard" :term:`parcellation`. For instance, the :mod:`nilearn.datasets` has functions to download atlases forming reference :term:`parcellation`, e.g., :func:`fetch_atlas_craddock_2012`, :func:`fetch_atlas_harvard_oxford`, :func:`fetch_atlas_yeo_2011`. For instance to retrieve the Harvard-Oxford cortical :term:`parcellation`, sampled at 2mm, and with a threshold of a probability of 0.25:: from nilearn import datasets dataset = datasets.fetch_atlas_harvard_oxford('cort-maxprob-thr25-2mm') atlas_filename = dataset.maps labels = dataset.labels Plotting can then be done as:: from nilearn import plotting plotting.plot_roi(atlas_filename) .. image:: ../auto_examples/01_plotting/images/sphx_glr_plot_atlas_001.png :target: ../auto_examples/01_plotting/plot_atlas.html :scale: 60 .. seealso:: * The :ref:`plotting documentation `; * The :ref:`dataset downloaders `. Extracting signals on a parcellation ------------------------------------ .. currentmodule:: nilearn.maskers To extract signal on the :term:`parcellation`, the easiest option is to use the :class:`NiftiLabelsMasker`. As any "maskers" in nilearn, it is a processing object that is created by specifying all the important parameters, but not the data:: from nilearn.maskers import NiftiLabelsMasker masker = NiftiLabelsMasker(labels_img=atlas_filename, standardize=True) The Nifti data can then be turned to time-series by calling the :meth:`NiftiLabelsMasker.fit_transform` method, that takes either filenames or `NiftiImage objects `_:: time_series = masker.fit_transform(frmi_files, confounds=confounds_dataframe) | Note that confound signals can be specified in the call. Indeed, to obtain time series that capture well the functional interactions between regions, regressing out noise sources is very important (:footcite:t:`Varoquaux2013`). For data processed by :term:`fMRIPrep`, :func:`~nilearn.interfaces.fmriprep.load_confounds` and :func:`~nilearn.interfaces.fmriprep.load_confounds_strategy` can help you retrieve confound variables. :func:`~nilearn.interfaces.fmriprep.load_confounds_strategy` selects confounds based on past literature with limited parameters for customisation. For more freedoms of confounds selection, :func:`~nilearn.interfaces.fmriprep.load_confounds` groups confound variables as sets of noise components and one can fine tune each of the parameters. .. image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_signal_extraction_001.png :target: ../auto_examples/03_connectivity/plot_signal_extraction.html :scale: 40 .. image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_signal_extraction_002.png :target: ../auto_examples/03_connectivity/plot_signal_extraction.html :scale: 40 .. topic:: **Full example** See the following example for a full file running the analysis: :ref:`sphx_glr_auto_examples_03_connectivity_plot_signal_extraction.py`. .. topic:: **Exercise: computing the correlation matrix of rest fmri** :class: green Try using the information above to compute the correlation matrix of the first subject of the brain development dataset downloaded with :func:`nilearn.datasets.fetch_development_fmri`. **Hints:** * Inspect the '.keys()' of the object returned by :func:`nilearn.datasets.fetch_development_fmri`. * Use :func:`~nilearn.interfaces.fmriprep.load_confounds` to get a set of confounds of your choice. (Note: CompCor and ICA-AROMA related options are not applicable to the brain development dataset). * Use :func:`~nilearn.interfaces.fmriprep.load_confounds_strategy` to get a set of confounds. (Note: only ``simple`` and ``scrubbing`` are applicable to the brain development dataset). * :class:`nilearn.connectome.ConnectivityMeasure` can be used to compute a correlation matrix (check the shape of your matrices). * :func:`matplotlib.pyplot.imshow` can show a correlation matrix. * The example above has the solution. | Time-series from a probabilistic atlas ====================================== Probabilistic atlases --------------------- The definition of regions as by a continuous probability map captures better our imperfect knowledge of boundaries in brain images (notably because of inter-subject registration errors). One example of such an atlas well suited to :term:`resting-state` or naturalistic-stimuli data analysis is the `MSDL atlas `_ (:func:`nilearn.datasets.fetch_atlas_msdl`). Probabilistic atlases are represented as a set of continuous maps, in a 4D nifti image. Visualization the atlas thus requires to visualize each of these maps, which requires accessing them with :func:`nilearn.image.index_img` (see the :ref:`corresponding example `). .. image:: ../auto_examples/01_plotting/images/sphx_glr_plot_overlay_001.png :target: ../auto_examples/01_plotting/plot_overlay.html :scale: 60 Extracting signals from a probabilistic atlas --------------------------------------------- .. currentmodule:: nilearn.maskers As with extraction of signals on a :term:`parcellation`, extracting signals from a :term:`probabilistic atlas` can be done with a "masker" object: the :class:`NiftiMapsMasker`. It is created by specifying the important parameters, in particular the atlas:: from nilearn.maskers import NiftiMapsMasker masker = NiftiMapsMasker(maps_img=atlas_filename, standardize=True) The ``fit_transform`` method turns filenames or `NiftiImage objects `_ to time series:: time_series = masker.fit_transform(frmi_files, confounds=csv_file) The procedure is the same as with `brain parcellations `_ but using the :class:`NiftiMapsMasker`, and the same considerations on using confounds regressors apply. .. image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_probabilistic_atlas_extraction_001.png :target: ../auto_examples/03_connectivity/plot_probabilistic_atlas_extraction.html :scale: 40 .. topic:: **Full example** A full example of extracting signals on a probabilistic: :ref:`sphx_glr_auto_examples_03_connectivity_plot_probabilistic_atlas_extraction.py`. .. topic:: **Exercise: correlation matrix of rest fMRI on probabilistic atlas** :class: green Try to compute the correlation matrix of the first subject of the brain development dataset downloaded with :func:`nilearn.datasets.fetch_development_fmri` with the MSDL atlas downloaded via :func:`nilearn.datasets.fetch_atlas_msdl`. **Hint:** The example above has the solution. A functional connectome: a graph of interactions ================================================ A square matrix, such as a correlation matrix, can also be seen as a `"graph" `_: a set of "nodes", connected by "edges". When these nodes are brain regions, and the edges capture interactions between them, this graph is a "functional connectome". We can display it with the :func:`nilearn.plotting.plot_connectome` function that take the matrix, and coordinates of the nodes in :term:`MNI` space. In the case of the MSDL atlas (:func:`nilearn.datasets.fetch_atlas_msdl`), the CSV file readily comes with :term:`MNI` coordinates for each region (see for instance example: :ref:`sphx_glr_auto_examples_03_connectivity_plot_probabilistic_atlas_extraction.py`). .. image:: ../auto_examples/03_connectivity/images/sphx_glr_plot_probabilistic_atlas_extraction_002.png :target: ../auto_examples/03_connectivity/plot_probabilistic_atlas_extraction.html As you can see, the correlation matrix gives a very "full" graph: every node is connected to every other one. This is because it also captures indirect connections. In the next section we will see how to focus on direct connections only. A functional connectome: extracting coordinates of regions ========================================================== For atlases without readily available label coordinates, center coordinates can be computed for each region on hard :term:`parcellation` or probabilistic atlases. * For hard :term:`parcellation` atlases (eg. :func:`nilearn.datasets.fetch_atlas_destrieux_2009`), use the :func:`nilearn.plotting.find_parcellation_cut_coords` function. See example: :ref:`sphx_glr_auto_examples_03_connectivity_plot_atlas_comparison.py` * For probabilistic atlases (eg. :func:`nilearn.datasets.fetch_atlas_msdl`), use the :func:`nilearn.plotting.find_probabilistic_atlas_cut_coords` function. See example: :ref:`sphx_glr_auto_examples_03_connectivity_plot_multi_subject_connectome.py`: .. code-block:: default from nilearn import plotting atlas_region_coords = plotting.find_probabilistic_atlas_cut_coords(atlas_filename) | .. topic:: **References** * On the use of correlation as a measure of network connectivity :footcite:p:`zalesky2012use` * Learning and comparing functional connectomes across subjects :footcite:p:`Varoquaux2013` References ---------- .. footbibliography::