ENH: Confound model enhancement

.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 @ git+https://github.com/poldracklab/niworkflows.git@'
     'e8f677a0407fc312b7f3d87a4c47726ceb8cd975',
@@ -104,6 +105,8 @@
 
 
 LINKS_REQUIRES = [
+    'git+https://github.com/nipy/nipype.git@'
+    'd353f0d879826031334b09d33e9443b8c9b3e7fe#egg=nipype',
     'git+https://github.com/poldracklab/niworkflows.git@'
     'e8f677a0407fc312b7f3d87a4c47726ceb8cd975#egg=niworkflows',
 ]

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},

fmriprep/workflows/base.py

@@ -55,6 +55,9 @@ def init_fmriprep_wf(
     omp_nthreads,
     output_dir,
     output_spaces,
+    regressors_all_comps,
+    regressors_dvars_th,
+    regressors_fd_th,
     run_uuid,
     skull_strip_fixed_seed,
     skull_strip_template,
@@ -105,6 +108,9 @@ def init_fmriprep_wf(
             output_spaces=OrderedDict([
                 ('MNI152Lin', {}), ('fsaverage', {'density': '10k'}),
                 ('T1w', {}), ('fsnative', {})]),
+            regressors_all_comps=False,
+            regressors_dvars_th=1.5,
+            regressors_fd_th=0.5,
             run_uuid='X',
             skull_strip_fixed_seed=False,
             skull_strip_template='OASIS30ANTs',
@@ -120,43 +126,44 @@ def init_fmriprep_wf(
 
     Parameters
 
-        layout : BIDSLayout object
-            BIDS dataset layout
-        subject_list : list
-            List of subject labels
-        task_id : str or None
-            Task ID of BOLD series to preprocess, or ``None`` to preprocess all
+        anat_only : bool
+            Disable functional workflows
+        bold2t1w_dof : 6, 9 or 12
+            Degrees-of-freedom for BOLD-T1w registration
+        cifti_output : bool
+            Generate bold CIFTI file in output spaces
+        debug : bool
+            Enable debugging outputs
         echo_idx : int or None
             Index of echo to preprocess in multiecho BOLD series,
             or ``None`` to preprocess all
-        run_uuid : str
-            Unique identifier for execution instance
-        work_dir : str
-            Directory in which to store workflow execution state and temporary files
-        output_dir : str
-            Directory in which to save derivatives
+        err_on_aroma_warn : bool
+            Do not fail on ICA-AROMA errors
+        fmap_bspline : bool
+            **Experimental**: Fit B-Spline field using least-squares
+        fmap_demean : bool
+            Demean voxel-shift map during unwarp
+        force_syn : bool
+            **Temporary**: Always run SyN-based SDC
+        freesurfer : bool
+            Enable FreeSurfer surface reconstruction (may increase runtime)
+        hires : bool
+            Enable sub-millimeter preprocessing in FreeSurfer
         ignore : list
             Preprocessing steps to skip (may include "slicetiming", "fieldmaps")
-        debug : bool
-            Enable debugging outputs
-        low_mem : bool
-            Write uncompressed .nii files in some cases to reduce memory usage
-        anat_only : bool
-            Disable functional workflows
+        layout : BIDSLayout object
+            BIDS dataset layout
         longitudinal : bool
             Treat multiple sessions as longitudinal (may increase runtime)
             See sub-workflows for specific differences
-        t2s_coreg : bool
-            For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistration
+        low_mem : bool
+            Write uncompressed .nii files in some cases to reduce memory usage
+        medial_surface_nan : bool
+            Replace medial wall values with NaNs on functional GIFTI files
         omp_nthreads : int
             Maximum number of threads an individual process may use
-        skull_strip_template : str
-            Name of ANTs skull-stripping template ('OASIS30ANTs' or 'NKI')
-        skull_strip_fixed_seed : bool
-            Do not use a random seed for skull-stripping - will ensure
-            run-to-run replicability when used with --omp-nthreads 1
-        freesurfer : bool
-            Enable FreeSurfer surface reconstruction (may increase runtime)
+        output_dir : str
+            Directory in which to save derivatives
         output_spaces : OrderedDict
             Ordered dictionary where keys are TemplateFlow ID strings (e.g. ``MNI152Lin``,
             ``MNI152NLin6Asym``, ``MNI152NLin2009cAsym``, or ``fsLR``) strings designating
@@ -165,30 +172,35 @@ def init_fmriprep_wf(
             Values of the dictionary aggregate modifiers (e.g. the value for the key ``MNI152Lin``
             could be ``{'resolution': 2}`` if one wants the resampling to be done on the 2mm
             resolution version of the selected template).
-        medial_surface_nan : bool
-            Replace medial wall values with NaNs on functional GIFTI files
-        cifti_output : bool
-            Generate bold CIFTI file in output spaces
-        hires : bool
-            Enable sub-millimeter preprocessing in FreeSurfer
+        regressors_all_comps
+            Return all CompCor component time series instead of the top fraction
+        regressors_dvars_th
+            Criterion for flagging DVARS outliers
+        regressors_fd_th
+            Criterion for flagging framewise displacement outliers
+        run_uuid : str
+            Unique identifier for execution instance
+        skull_strip_template : str
+            Name of ANTs skull-stripping template ('OASIS30ANTs' or 'NKI')
+        skull_strip_fixed_seed : bool
+            Do not use a random seed for skull-stripping - will ensure
+            run-to-run replicability when used with --omp-nthreads 1
+        subject_list : list
+            List of subject labels
+        t2s_coreg : bool
+            For multi-echo EPI, use the calculated T2*-map for T2*-driven coregistration
+        task_id : str or None
+            Task ID of BOLD series to preprocess, or ``None`` to preprocess all
+        use_aroma : bool
+            Perform ICA-AROMA on MNI-resampled functional series
         use_bbr : bool or None
             Enable/disable boundary-based registration refinement.
             If ``None``, test BBR result for distortion before accepting.
-        bold2t1w_dof : 6, 9 or 12
-            Degrees-of-freedom for BOLD-T1w registration
-        fmap_bspline : bool
-            **Experimental**: Fit B-Spline field using least-squares
-        fmap_demean : bool
-            Demean voxel-shift map during unwarp
         use_syn : bool
             **Experimental**: Enable ANTs SyN-based susceptibility distortion correction (SDC).
             If fieldmaps are present and enabled, this is not run, by default.
-        force_syn : bool
-            **Temporary**: Always run SyN-based SDC
-        use_aroma : bool
-            Perform ICA-AROMA on MNI-resampled functional series
-        err_on_aroma_warn : bool
-            Do not fail on ICA-AROMA errors
+        work_dir : str
+            Directory in which to store workflow execution state and temporary files
 
     """
     fmriprep_wf = Workflow(name='fmriprep_wf')
@@ -236,6 +248,9 @@ def init_fmriprep_wf(
             use_aroma=use_aroma,
             aroma_melodic_dim=aroma_melodic_dim,
             err_on_aroma_warn=err_on_aroma_warn,
+            regressors_all_comps=regressors_all_comps,
+            regressors_fd_th=regressors_fd_th,
+            regressors_dvars_th=regressors_dvars_th,
         )
 
         single_subject_wf.config['execution']['crashdump_dir'] = (
@@ -275,6 +290,9 @@ def init_single_subject_wf(
     output_dir,
     output_spaces,
     reportlets_dir,
+    regressors_all_comps,
+    regressors_dvars_th,
+    regressors_fd_th,
     skull_strip_fixed_seed,
     skull_strip_template,
     subject_id,
@@ -326,6 +344,9 @@ def init_single_subject_wf(
                 ('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',
@@ -392,6 +413,12 @@ def init_single_subject_wf(
             resolution version of the selected template).
         reportlets_dir : str
             Directory in which to save reportlets
+        regressors_all_comps
+            Return all CompCor component time series instead of the top fraction
+        regressors_fd_th
+            Criterion for flagging framewise displacement outliers
+        regressors_dvars_th
+            Criterion for flagging DVARS outliers
         skull_strip_fixed_seed : bool
             Do not use a random seed for skull-stripping - will ensure
             run-to-run replicability when used with --omp-nthreads 1
@@ -412,6 +439,7 @@ def init_single_subject_wf(
             **Experimental**: Enable ANTs SyN-based susceptibility distortion correction (SDC).
             If fieldmaps are present and enabled, this is not run, by default.
 
+
     Inputs
 
         subjects_dir
@@ -560,6 +588,9 @@ def init_single_subject_wf(
             output_dir=output_dir,
             output_spaces=output_spaces,
             reportlets_dir=reportlets_dir,
+            regressors_all_comps=regressors_all_comps,
+            regressors_fd_th=regressors_fd_th,
+            regressors_dvars_th=regressors_dvars_th,
             t2s_coreg=t2s_coreg,
             use_aroma=use_aroma,
             use_bbr=use_bbr,