Merge pull request #1586 from oesteban/pr/1487

ENH: Confound model enhancement

Author: oesteban

.circleci/ds005_outputs.txt

@@ -53,6 +53,7 @@ fmriprep/sub-01/func
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_AROMAnoiseICs.csv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_bold.dtseries.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_bold.dtseries.nii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_desc-confounds_regressors.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_desc-confounds_regressors.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_desc-MELODIC_mixing.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-fsaverage5_hemi-L.func.gii
@@ -85,6 +86,7 @@ fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-01_space-T1w_desc-preproc_
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_AROMAnoiseICs.csv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.dtseries.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.dtseries.nii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-MELODIC_mixing.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage5_hemi-L.func.gii

.circleci/ds005_partial_outputs.txt

@@ -53,6 +53,7 @@ fmriprep/sub-01/func
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_AROMAnoiseICs.csv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.dtseries.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_bold.dtseries.nii
+fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.json
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-confounds_regressors.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_desc-MELODIC_mixing.tsv
 fmriprep/sub-01/func/sub-01_task-mixedgamblestask_run-02_space-fsaverage5_hemi-L.func.gii

.circleci/ds054_outputs.txt

@@ -27,6 +27,7 @@ fmriprep/sub-100185/anat/sub-100185_space-MNI152NLin2009cAsym_label-CSF_probseg.
 fmriprep/sub-100185/anat/sub-100185_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz
 fmriprep/sub-100185/anat/sub-100185_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz
 fmriprep/sub-100185/func
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_desc-confounds_regressors.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_desc-confounds_regressors.tsv
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_space-MNI152NLin2009cAsym_boldref.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_space-MNI152NLin2009cAsym_desc-brain_mask.json
@@ -38,6 +39,7 @@ fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_space-T1w_desc-brain
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_space-T1w_desc-brain_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_space-T1w_desc-preproc_bold.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-01_space-T1w_desc-preproc_bold.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-02_desc-confounds_regressors.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-02_desc-confounds_regressors.tsv
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-02_space-MNI152NLin2009cAsym_boldref.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-02_space-MNI152NLin2009cAsym_desc-brain_mask.json

.circleci/ds210_outputs.txt

@@ -27,6 +27,7 @@ fmriprep/sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz
 fmriprep/sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz
 fmriprep/sub-02/anat/sub-02_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz
 fmriprep/sub-02/func
+fmriprep/sub-02/func/sub-02_task-cuedSGT_run-01_desc-confounds_regressors.json
 fmriprep/sub-02/func/sub-02_task-cuedSGT_run-01_desc-confounds_regressors.tsv
 fmriprep/sub-02/func/sub-02_task-cuedSGT_run-01_space-MNI152NLin2009cAsym_boldref.nii.gz
 fmriprep/sub-02/func/sub-02_task-cuedSGT_run-01_space-MNI152NLin2009cAsym_desc-brain_mask.json

.zenodo.json

@@ -116,6 +116,11 @@
       "affiliation": "Neuroscience Program, University of Iowa",
       "orcid": "0000-0002-3339-4857"
     },
+    {
+      "name": "Ciric, Rastko",
+      "affiliation": "Stanford University",
+      "orcid": "0000-0001-6347-7939"
+    },
     {
       "name": "Poldrack, Russell A.",
       "affiliation": "Department of Psychology, Stanford University",

docs/outputs.rst

@@ -173,7 +173,7 @@ motion-correction parameters estimated by fMRIPrep;
 if present, ``non_steady_state_outlier_XX`` columns indicate non-steady state volumes with a single
 ``1`` value and ``0`` elsewhere (*i.e.*, there is one ``non_steady_state_outlier_XX`` column per
 outlier/volume);
-six noise components are calculated using :abbr:`CompCor (Component Based Noise Correction)`, 
+additional noise components are calculated using :abbr:`CompCor (Component Based Noise Correction)`,
 according to both the anatomical (``a_comp_cor_XX``) and temporal (``t_comp_cor_XX``) variants;
 and the motion-related components identified by
 :abbr:`ICA (independent components analysis)`-:abbr:`AROMA (Automatic Removal Of Motion Artifacts)`

docs/workflows.rst

@@ -46,6 +46,9 @@ is presented below:
             ('MNI152Lin', {}), ('fsaverage', {'density': '10k'}),
             ('T1w', {}), ('fsnative', {})]),
         reportlets_dir='.',
+        regressors_all_comps=False,
+        regressors_dvars_th=1.5,
+        regressors_fd_th=0.5,
         skull_strip_fixed_seed=False,
         skull_strip_template='OASIS30ANTs',
         subject_id='test',
@@ -299,6 +302,9 @@ BOLD preprocessing
         reportlets_dir='.',
         t2s_coreg=False,
         use_aroma=False,
+        regressors_all_comps=False,
+        regressors_fd_th=0.5,
+        regressors_dvars_th=1.5,
         use_bbr=True,
         use_syn=True,
         layout=BIDSLayout('.'),
@@ -543,7 +549,11 @@ Confounds estimation
         name="discover_wf",
         mem_gb=1,
         metadata={"RepetitionTime": 2.0,
-                  "SliceTiming": [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]})
+                  "SliceTiming": [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]},
+        regressors_all_comps=False,
+        regressors_dvars_th=1.5,
+        regressors_fd_th=0.5,
+    )
 
 Given a motion-corrected fMRI, a brain mask, ``mcflirt`` movement parameters and a
 segmentation, the `discover_wf` sub-workflow calculates potential

fmriprep/__about__.py

@@ -86,7 +86,8 @@
     'indexed_gzip>=0.8.8',
     'nibabel>=2.2.1',
     'nilearn!=0.5.0,!=0.5.1',
-    'nipype>=1.1.6',
+    'nipype @ git+https://github.com/nipy/nipype.git@'
+    'd353f0d879826031334b09d33e9443b8c9b3e7fe',
     'nitime',
     'niworkflows<0.10.0a0,>=0.9.1.post1',
     'numpy',
@@ -103,6 +104,8 @@
 
 
 LINKS_REQUIRES = [
+    'git+https://github.com/nipy/nipype.git@'
+    'd353f0d879826031334b09d33e9443b8c9b3e7fe#egg=nipype',
 ]
 
 TESTS_REQUIRES = [

fmriprep/cli/run.py

@@ -182,6 +182,22 @@ def get_parser():
                          help='Exact or maximum number of MELODIC components to estimate '
                          '(positive = exact, negative = maximum)')
 
+    # Confounds options
+    g_confounds = parser.add_argument_group('Specific options for estimating confounds')
+    g_confounds.add_argument(
+        '--return-all-components', required=False, action='store_true', default=False,
+        help='Include all components estimated in CompCor decomposition in the confounds '
+             'file instead of only the components sufficient to explain 50 percent of '
+             'BOLD variance in each CompCor mask')
+    g_confounds.add_argument(
+        '--fd-spike-threshold', required=False, action='store', default=0.5, type=float,
+        help='Threshold for flagging a frame as an outlier on the basis of framewise '
+             'displacement')
+    g_confounds.add_argument(
+        '--dvars-spike-threshold', required=False, action='store', default=1.5, type=float,
+        help='Threshold for flagging a frame as an outlier on the basis of standardised '
+             'DVARS')
+
     #  ANTs options
     g_ants = parser.add_argument_group('Specific options for ANTs registrations')
     g_ants.add_argument('--skull-strip-template', action='store', default='OASIS30ANTs',
@@ -574,6 +590,9 @@ def build_workflow(opts, retval):
         output_dir=str(output_dir),
         output_spaces=output_spaces,
         run_uuid=run_uuid,
+        regressors_all_comps=opts.return_all_components,
+        regressors_fd_th=opts.fd_spike_threshold,
+        regressors_dvars_th=opts.dvars_spike_threshold,
         skull_strip_fixed_seed=opts.skull_strip_fixed_seed,
         skull_strip_template=opts.skull_strip_template,
         subject_list=subject_list,

fmriprep/data/boilerplate.bib

@@ -241,6 +241,20 @@ @article{power_fd_dvars
     year = 2014
 }
 
+@article{confounds_satterthwaite_2013,
+    author = {Satterthwaite, Theodore D. and Elliott, Mark A. and Gerraty, Raphael T. and Ruparel, Kosha and Loughead, James and Calkins, Monica E. and Eickhoff, Simon B. and Hakonarson, Hakon and Gur, Ruben C. and Gur, Raquel E. and Wolf, Daniel H.},
+    doi = {10.1016/j.neuroimage.2012.08.052},
+    issn = {10538119},
+    journal = {NeuroImage},
+    number = 1,
+    pages = {240--256},
+    title = {{An improved framework for confound regression and filtering for control of motion artifact in the preprocessing of resting-state functional connectivity data}},
+    url = {http://linkinghub.elsevier.com/retrieve/pii/S1053811912008609},
+    volume = 64,
+    year = 2013
+}
+
+
 @article{nilearn,
     author = {Abraham, Alexandre and Pedregosa, Fabian and Eickenberg, Michael and Gervais, Philippe and Mueller, Andreas and Kossaifi, Jean and Gramfort, Alexandre and Thirion, Bertrand and Varoquaux, Gael},
     doi = {10.3389/fninf.2014.00014},