[NF] get fmriprep confounds with fixed strategy (#3016)

* [NF] get fmriprep confounds with fixed strategy Closes #2946. This is the second part to merge pacakge `load_confounds`. * Add predefined strategy with a dictionary containing relevant parameters * New function fmriprep_confounds_strategy to parse user input for the predefined strategy * Add example and brief explaination of the four based strategy The example is super preliminary, please raise any suggestion and better way to introduce the function. Co-authored-by: Pierre Bellec <pierre.bellec@gmail.com> * LINT pep8 * DOCS limit of example dataset Some confound variables are not availible in the reduced experimental dataset Comment out the lines for now to let the test pass * Typos Co-authored-by: bthirion <bertrand.thirion@inria.fr> * Apply suggestions from code review Co-authored-by: Gensollen <nicolas.gensollen@gmail.com> * EHN raise error for invalid strategy Remove examples that cannot be executed correctly * LINT flake8 * Apply suggestions from code review Co-authored-by: Gensollen <nicolas.gensollen@gmail.com> * [DOCS] maybe demostrate the results of denoising through PCA * [TEST] factorise checks on preset strategy defaults * [DOCS] add a table to summarise the strategies * [DOCS] skip the table for pep8 * [FIX] remove irrelevant stuff added by my IDE * [DOCS]syntax error when referencing the functions * [FIX] simple strategy motion default should be 'full' * [DOC] fix the broken example due to change in default setting and limit of the example dataset * DOCS move strategy description from example to the function docstring * [circle-full] Add descriptions of fmriprep_confounds in the user guide * Apply suggestions from code review Co-authored-by: Gensollen <nicolas.gensollen@gmail.com> Co-authored-by: bthirion <bertrand.thirion@inria.fr> * [circle full] Fix the table formatting * DOCS fix sections in examples * [circle full] Trigger full build Co-authored-by: Pierre Bellec <pierre.bellec@gmail.com> Co-authored-by: bthirion <bertrand.thirion@inria.fr> Co-authored-by: Gensollen <nicolas.gensollen@gmail.com>
nilearn · Oct 29, 2021 · d16198d · d16198d
1 parent 708bbb8
commit d16198d
Show file tree

Hide file tree

Showing 12 changed files with 505 additions and 11 deletions.
diff --git a/doc/connectivity/functional_connectomes.rst b/doc/connectivity/functional_connectomes.rst
@@ -78,14 +78,22 @@ The Nifti data can then be turned to time-series by calling the
 filenames or `NiftiImage objects
 <http://nipy.org/nibabel/nibabel_images.html>`_::
 
-    time_series = masker.fit_transform(frmi_files, confounds=csv_file)
+    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 indeed very important
+regions, regressing out noise sources is very important
 `[Varoquaux & Craddock 2013] <https://hal.inria.fr/hal-00812911/>`_.
+For data processed by :term:`fMRIPrep`,
+:func:`fmriprep_confounds` and
+:func:`fmriprep_confounds_strategy` can help you retrieve
+confound variables. :func:`fmriprep_confounds_strategy` selects confounds based
+on past literature with limited parameters for customisation. For more freedoms
+of confounds selection, :func:`fmriprep_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
@@ -112,6 +120,14 @@ regions, regressing out noise sources is indeed very important
    * Inspect the '.keys()' of the object returned by
      :func:`nilearn.datasets.fetch_development_fmri`.
 
+   * Use :func:`fmriprep_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:`fmriprep_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).
 

diff --git a/doc/manipulating_images/masker_objects.rst b/doc/manipulating_images/masker_objects.rst
@@ -268,7 +268,10 @@ properties, before conversion to voxel signals.
 
   * More complex confounds, measured during the acquision, can be removed
     by passing them to :meth:`NiftiMasker.transform`. If the dataset
-    provides a confounds file, just pass its path to the masker.
+    provides a confounds file, just pass its path to the masker. For
+    :term:`fMRIPrep` outputs, one can use :func:`fmriprep_confounds` or
+    :func:`fmriprep_confounds_strategy` to select confound variables with some
+    basic sanity check based on :term:`fMRIPrep` documentation.
 
 .. topic:: **Exercise**
    :class: green
@@ -279,6 +282,11 @@ properties, before conversion to voxel signals.
    Try to enable detrending and run the script:
    does it have a big impact on the result?
 
+.. note::
+
+   Please see the usage example of :func:`fmriprep_confounds` and
+   :func:`fmriprep_confounds_strategy` in
+   :doc:`plot_signal_extraction.py <../auto_examples/03_connectivity/plot_signal_extraction>`.
 
 .. seealso::
 

diff --git a/doc/modules/reference.rst b/doc/modules/reference.rst
@@ -234,6 +234,7 @@ the :ref:`user guide <user_guide>` for more information and usage examples.
    :template: function.rst
 
    fmriprep_confounds
+   fmriprep_confounds_strategy
 
 .. _masking_ref:
 

diff --git a/doc/references.bib b/doc/references.bib
@@ -389,6 +389,20 @@ @article{Fonov2009
 	year = {2009},
 }
 
+@article{Fox2005,
+	title = {The human brain is intrinsically organized into dynamic, anticorrelated functional networks},
+	volume = {102},
+	issn = {0027-8424},
+	doi = {10.1073/pnas.0504136102},
+	number = {27},
+	journal = {Proceedings of the National Academy of Sciences},
+	author = {Fox, Michael D. and Snyder, Abraham Z. and Vincent, Justin L and Corbetta, Maurizio and Van Essen, David C. and Raichle, Marcus E.},
+	month = jul,
+	year = {2005},
+	pmid = {15976020},
+	pages = {9673--9678},
+}
+
 @article{Friston1994,
 	author = {Friston, K. J. and Holmes, A. P. and Worsley, K. J. and Poline, J.-P. and Frith, C. D. and Frackowiak, R. S. J.},
 	title = {Statistical parametric maps in functional imaging: A general linear approach},
@@ -705,6 +719,19 @@ @article{PAPADOPOULOSORFANOS2017309
 	abstract = {The Brainomics/Localizer database exposes part of the data collected by the in-house Localizer project, which planned to acquire four types of data from volunteer research subjects: anatomical MRI scans, functional MRI data, behavioral and demographic data, and DNA sampling. Over the years, this local project has been collecting such data from hundreds of subjects. We had selected 94 of these subjects for their complete datasets, including all four types of data, as the basis for a prior publication; the Brainomics/Localizer database publishes the data associated with these 94 subjects. Since regulatory rules prevent us from making genetic data available for download, the database serves only anatomical MRI scans, functional MRI data, behavioral and demographic data. To publish this set of heterogeneous data, we use dedicated software based on the open-source CubicWeb semantic web framework. Through genericity in the data model and flexibility in the display of data (web pages, CSV, JSON, XML), CubicWeb helps us expose these complex datasets in original and efficient ways.}
 }
 
+@article{Parker2018,
+	title = {An evaluation of the efficacy, reliability, and sensitivity of motion correction strategies for resting-state functional {MRI}},
+	volume = {171},
+	issn = {1095-9572},
+	doi = {10.1016/j.neuroimage.2017.12.073},
+	journal = {NeuroImage},
+	author = {Parkes, Linden and Fulcher, Ben and Yücel, Murat and Fornito, Alex},
+	month = may,
+	year = {2018},
+	pmid = {29278773},
+	pages = {415--436},
+}
+
 @Article{Pauli2018probabilistic,
 	author={Pauli, Wolfgang M.
 	and Nili, Amanda N.

diff --git a/doc/whats_new.rst b/doc/whats_new.rst
@@ -9,6 +9,9 @@ NEW
   import and encouraged to update to more recent versions of Python.
 - New function :func:`nilearn.input_data.fmriprep_confounds` to load confound variables easily
   from :term:`fMRIPrep` outputs.
+- New function :func:`nilearn.input_data.fmriprep_confounds_strategy` to load confound variables 
+  from :term:`fMRIPrep` outputs using four preset strategies: ``simple``, ``scrubbing``, 
+  ``compcor``, ``ica_aroma``.
 - Surface plotting functions like :func:`nilearn.plotting.plot_surf_stat_map`
   now have an `engine` parameter, defaulting to "matplotlib", but which can be
   set to "plotly". If plotly and kaleido are installed, this will generate an

diff --git a/examples/03_connectivity/plot_signal_extraction.py b/examples/03_connectivity/plot_signal_extraction.py
@@ -74,7 +74,7 @@
 # first label
 # matrices are ordered for block-like representation
 plotting.plot_matrix(correlation_matrix, figure=(10, 8), labels=labels[1:],
-                     vmax=0.8, vmin=-0.8, title="Preset",
+                     vmax=0.8, vmin=-0.8, title="Confounds",
                      reorder=True)
 
 ##############################################################################
@@ -102,8 +102,12 @@
 # parameters to retrieve the relevant columns from the TSV file generated by
 # :term:`fMRIPrep`. :func:`nilearn.input_data.fmriprep_confounds` ensures
 # two things:
+#
 # 1. The correct regressors are selected with provided strategy, and
-# 2. Volumes such as non-steady-state volumes are masked out correctly.
+#
+# 2. Volumes such as non-steady-state and/or high motion volumes are masked
+#    out correctly.
+#
 # Let's try a simple strategy removing motion, white matter signal,
 # cerebrospinal fluid signal with high-pass filtering.
 
@@ -194,4 +198,60 @@
                      title='Motion, WM, CSF, GSR',
                      reorder=True)
 
+##############################################################################
+# Using predefined strategies
+# ---------------------------
+# Instead of customising the strategy through
+# :func:`nilearn.input_data.fmriprep_confounds`, one can use a predefined
+# strategy with :func:`nilearn.input_data.fmriprep_confounds_strategy`. Based
+# on the confound variables generated through :term:`fMRIPrep`, and past
+# benchmarks studies (:footcite:`Ciric2017`, :footcite:`Parker2018`): `simple`,
+# `scrubbing`, `compcor`, `ica_aroma`.
+# The following examples shows how to use the `simple` strategy and overwrite
+# the motion default to basic.
+
+from nilearn.input_data import fmriprep_confounds_strategy
+
+# use default parameters
+confounds, sample_mask = fmriprep_confounds_strategy(fmri_filenames,
+                                                     denoise_strategy="simple",
+                                                     motion="basic")
+
+time_series = masker.fit_transform(fmri_filenames,
+                                   confounds=confounds,
+                                   sample_mask=sample_mask)
+
+correlation_matrix = correlation_measure.fit_transform([time_series])[0]
+
+np.fill_diagonal(correlation_matrix, 0)
+
+plotting.plot_matrix(correlation_matrix, figure=(10, 8), labels=labels[1:],
+                     vmax=0.8, vmin=-0.8,
+                     title='simple',
+                     reorder=True)
+
+# add optional parameter global signal
+confounds, sample_mask = fmriprep_confounds_strategy(fmri_filenames,
+                                                     denoise_strategy="simple",
+                                                     motion="basic",
+                                                     global_signal="basic")
+time_series = masker.fit_transform(fmri_filenames,
+                                   confounds=confounds,
+                                   sample_mask=sample_mask)
+
+correlation_matrix = correlation_measure.fit_transform([time_series])[0]
+
+np.fill_diagonal(correlation_matrix, 0)
+
+plotting.plot_matrix(correlation_matrix, figure=(10, 8), labels=labels[1:],
+                     vmax=0.8, vmin=-0.8,
+                     title='simple with global signal',
+                     reorder=True)
+
 plotting.show()
+
+##############################################################################
+# References
+# ----------
+#
+#  .. footbibliography::
diff --git a/nilearn/input_data/__init__.py b/nilearn/input_data/__init__.py
@@ -8,6 +8,9 @@
 from .nifti_maps_masker import NiftiMapsMasker
 from .nifti_spheres_masker import NiftiSpheresMasker
 from .fmriprep_confounds import fmriprep_confounds
+from .fmriprep_confounds_strategy import fmriprep_confounds_strategy
+
 
 __all__ = ['NiftiMasker', 'MultiNiftiMasker', 'NiftiLabelsMasker',
-           'NiftiMapsMasker', 'NiftiSpheresMasker', 'fmriprep_confounds']
+           'NiftiMapsMasker', 'NiftiSpheresMasker',
+           'fmriprep_confounds', 'fmriprep_confounds_strategy']
diff --git a/nilearn/input_data/fmriprep_confounds.py b/nilearn/input_data/fmriprep_confounds.py
@@ -226,6 +226,10 @@ def fmriprep_confounds(img_files,
     aspects of the preprocessing listed in :footcite:`Ciric2017` are controlled
     through :term:`fMRIPrep`, e.g. distortion correction.
 
+    See Also
+    --------
+    :func:`nilearn.input_data.fmriprep_confounds_strategy`
+
     References
     -----------
     .. footbibliography::