Merge pull request #2248 from effigies/enh/debug

ENH: Output CompCor masks if ``--debug compcor`` is passed

Author: oesteban

.circleci/config.yml

@@ -601,7 +601,7 @@ jobs:
                 ${FASTRACK_ARG} \
                 --fs-no-reconall --sloppy \
                 --output-spaces MNI152NLin2009cAsym:res-2 anat func \
-                --mem_mb 4096 --nthreads 2 -vv
+                --mem_mb 4096 --nthreads 2 -vv --debug compcor
       - run:
           name: Checking outputs of fMRIPrep
           command: |

.circleci/ds054_fasttrack_outputs.txt

@@ -13,6 +13,10 @@ fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-brain_mask.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-brain_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-confounds_timeseries.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-confounds_timeseries.tsv
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorA_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorC_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorT_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorW_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-preproc_bold.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-preproc_bold.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_from-scanner_to-T1w_mode-image_xfm.txt
@@ -32,6 +36,10 @@ fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-brain_mask.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-brain_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-confounds_timeseries.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-confounds_timeseries.tsv
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorA_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorC_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorT_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorW_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-preproc_bold.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-preproc_bold.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_from-scanner_to-T1w_mode-image_xfm.txt

.circleci/ds054_outputs.txt

@@ -32,6 +32,10 @@ fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-brain_mask.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-brain_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-confounds_timeseries.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-confounds_timeseries.tsv
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorA_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorC_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorT_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-CompCorW_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-preproc_bold.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_desc-preproc_bold.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-1_from-scanner_to-T1w_mode-image_xfm.txt
@@ -51,6 +55,10 @@ fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-brain_mask.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-brain_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-confounds_timeseries.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-confounds_timeseries.tsv
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorA_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorC_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorT_mask.nii.gz
+fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-CompCorW_mask.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-preproc_bold.json
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_desc-preproc_bold.nii.gz
 fmriprep/sub-100185/func/sub-100185_task-machinegame_run-2_from-scanner_to-T1w_mode-image_xfm.txt

fmriprep/cli/parser.py

@@ -533,9 +533,16 @@ def _bids_filter(value):
         "improve FMRIPREP and provides an indicator of real "
         "world usage crucial for obtaining funding.",
     )
+    g_other.add_argument(
+        "--debug",
+        action="store",
+        nargs="+",
+        choices=config.DEBUG_MODES + ("all",),
+        help="Debug mode(s) to enable. 'all' is alias for all available modes.",
+    )
+
     g_other.add_argument(
         "--sloppy",
-        dest="debug",
         action="store_true",
         default=False,
         help="Use low-quality tools for speed - TESTING ONLY",

fmriprep/config.py

@@ -187,6 +187,11 @@
     pass
 
 
+# Debug modes are names that influence the exposure of internal details to
+# the user, either through additional derivatives or increased verbosity
+DEBUG_MODES = ("compcor",)
+
+
 class _Config:
     """An abstract class forbidding instantiation."""
 
@@ -359,8 +364,10 @@ class execution(_Config):
     """A dictionary of BIDS selection filters."""
     boilerplate_only = False
     """Only generate a boilerplate."""
-    debug = False
+    sloppy = False
     """Run in sloppy mode (meaning, suboptimal parameters that minimize run-time)."""
+    debug = []
+    """Debug mode(s)."""
     echo_idx = None
     """Select a particular echo for multi-echo EPI datasets."""
     fs_license_file = _fs_license
@@ -456,6 +463,9 @@ def init(cls):
                     for k, v in filters.items()
                 }
 
+        if "all" in cls.debug:
+            cls.debug = list(DEBUG_MODES)
+
 
 # These variables are not necessary anymore
 del _fs_license

fmriprep/workflows/base.py

@@ -237,7 +237,7 @@ def init_single_subject_wf(subject_id):
     # Preprocessing of T1w (includes registration to MNI)
     anat_preproc_wf = init_anat_preproc_wf(
         bids_root=str(config.execution.bids_dir),
-        debug=config.execution.debug is True,
+        debug=config.execution.sloppy,
         existing_derivatives=anat_derivatives,
         freesurfer=config.workflow.run_reconall,
         hires=config.workflow.hires,

fmriprep/workflows/bold/base.py

@@ -303,6 +303,8 @@ def init_func_preproc_wf(bold_file):
             ('cifti_metadata', 'inputnode.cifti_metadata'),
             ('cifti_density', 'inputnode.cifti_density'),
             ('confounds_metadata', 'inputnode.confounds_metadata'),
+            ('acompcor_masks', 'inputnode.acompcor_masks'),
+            ('tcompcor_mask', 'inputnode.tcompcor_mask'),
         ]),
     ])
 
@@ -333,7 +335,7 @@ def init_func_preproc_wf(bold_file):
         mem_gb=mem_gb['resampled'],
         name='bold_reg_wf',
         omp_nthreads=omp_nthreads,
-        sloppy=config.execution.debug,
+        sloppy=config.execution.sloppy,
         use_bbr=config.workflow.use_bbr,
         use_compression=False,
     )
@@ -404,7 +406,7 @@ def init_func_preproc_wf(bold_file):
     # SDC (SUSCEPTIBILITY DISTORTION CORRECTION) or bypass ##########################
     bold_sdc_wf = init_sdc_estimate_wf(fmaps, metadata,
                                        omp_nthreads=omp_nthreads,
-                                       debug=config.execution.debug)
+                                       debug=config.execution.sloppy)
 
     # MULTI-ECHO EPI DATA #############################################
     if multiecho:  # instantiate relevant interfaces, imports
@@ -496,9 +498,9 @@ def init_func_preproc_wf(bold_file):
             ('outputnode.bold_mask', 'inputnode.bold_mask')]),
         (bold_confounds_wf, outputnode, [
             ('outputnode.confounds_file', 'confounds'),
-        ]),
-        (bold_confounds_wf, outputnode, [
             ('outputnode.confounds_metadata', 'confounds_metadata'),
+            ('outputnode.acompcor_masks', 'acompcor_masks'),
+            ('outputnode.tcompcor_mask', 'tcompcor_mask'),
         ]),
         # Connect bold_bold_trans_wf
         (bold_split, bold_bold_trans_wf, [

fmriprep/workflows/bold/confounds.py

@@ -193,7 +193,7 @@ def init_bold_confs_wf(
                 'skip_vols', 't1w_mask', 't1w_tpms', 't1_bold_xform']),
         name='inputnode')
     outputnode = pe.Node(niu.IdentityInterface(
-        fields=['confounds_file', 'confounds_metadata']),
+        fields=['confounds_file', 'confounds_metadata', 'acompcor_masks', 'tcompcor_mask']),
         name='outputnode')
 
     # DVARS
@@ -392,6 +392,8 @@ def _select_cols(table):
         # Set outputs
         (spike_regress, outputnode, [('confounds_file', 'confounds_file')]),
         (mrg_conf_metadata2, outputnode, [('out_dict', 'confounds_metadata')]),
+        (tcompcor, outputnode, [("high_variance_masks", "tcompcor_mask")]),
+        (acc_msk_bin, outputnode, [("out_file", "acompcor_masks")]),
         (inputnode, rois_plot, [('bold', 'in_file'),
                                 ('bold_mask', 'in_mask')]),
         (tcompcor, mrg_compcor, [('high_variance_masks', 'in1')]),

fmriprep/workflows/bold/outputs.py

@@ -4,8 +4,9 @@
 from nipype.pipeline import engine as pe
 from nipype.interfaces import utility as niu
 
-from ...config import DEFAULT_MEMORY_MIN_GB
-from ...interfaces import DerivativesDataSink
+from fmriprep import config
+from fmriprep.config import DEFAULT_MEMORY_MIN_GB
+from fmriprep.interfaces import DerivativesDataSink
 
 
 def init_func_derivatives_wf(
@@ -62,7 +63,7 @@ def init_func_derivatives_wf(
         'bold_mask_native', 'cifti_variant', 'cifti_metadata', 'cifti_density',
         'confounds', 'confounds_metadata', 'melodic_mix', 'nonaggr_denoised_file',
         'source_file', 'surf_files', 'surf_refs', 'template', 'spatial_reference',
-        'bold2anat_xfm', 'anat2bold_xfm']),
+        'bold2anat_xfm', 'anat2bold_xfm', 'acompcor_masks', 'tcompcor_mask']),
         name='inputnode')
 
     raw_sources = pe.Node(niu.Function(function=_bids_relative), name='raw_sources')
@@ -338,6 +339,23 @@ def init_func_derivatives_wf(
                                         (('cifti_metadata', _read_json), 'meta_dict')])
         ])
 
+    if "compcor" in config.execution.debug:
+        ds_acompcor_masks = pe.Node(
+            DerivativesDataSink(
+                base_directory=output_dir, desc=[f"CompCor{_}" for _ in "CWA"],
+                suffix="mask", compress=True),
+            name="ds_acompcor_masks", run_without_submitting=True)
+        ds_tcompcor_mask = pe.Node(
+            DerivativesDataSink(
+                base_directory=output_dir, desc="CompCorT", suffix="mask", compress=True),
+            name="ds_tcompcor_mask", run_without_submitting=True)
+        workflow.connect([
+            (inputnode, ds_acompcor_masks, [("acompcor_masks", "in_file"),
+                                            ("source_file", "source_file")]),
+            (inputnode, ds_tcompcor_mask, [("tcompcor_mask", "in_file"),
+                                           ("source_file", "source_file")]),
+        ])
+
     return workflow