ENH : separate deep from shallow WM+CSF in the carpetplot (#2744)

This PR implements the proposition of @effigies (nipreps/niworkflows#651 (comment)) to separate the WM+CSF compartement in the carpetplot into the shallow WM+CSF and the deep WM+CSF corresponding to the aCompCor mask

docs/_static/SampleReport/sample_report.html

@@ -181,7 +181,7 @@ <h3 class="run-title">Variance explained by a/crown/tCompCor components</h3><p c
 
         </div>
         <div id="datatype-figures_desc-carpetplot_run-1_suffix-bold_task-mixedgamblestask">
-<h3 class="run-title">BOLD Summary</h3><p class="elem-caption">Summary statistics are plotted, which may reveal trends or artifacts in the BOLD data. Global signals calculated within the whole-brain (GS), within the white-matter (WM) and within cerebro-spinal fluid (CSF) show the mean BOLD signal in their corresponding masks. DVARS and FD show the standardized DVARS and framewise-displacement measures for each time point.<br /> A carpet plot shows the time series for all voxels within the brain mask, or if <code>--cifti-output</code> was enabled, all grayordinates. Voxels are grouped into cortical (dark/light blue), and subcortical (orange) gray matter, cerebellum (green) and white matter and CSF (red), indicated by the color map on the left-hand side.</p>                    <img class="svg-reportlet" src="./figures/sub-10_task-mixedgamblestask_run-1_desc-carpetplot_bold.svg" style="width: 100%" />
+<h3 class="run-title">BOLD Summary</h3><p class="elem-caption">Summary statistics are plotted, which may reveal trends or artifacts in the BOLD data. Global signals calculated within the whole-brain (GS), within the white-matter (WM) and within cerebro-spinal fluid (CSF) show the mean BOLD signal in their corresponding masks. DVARS and FD show the standardized DVARS and framewise-displacement measures for each time point.<br /> A carpet plot shows the time series for all voxels within the brain mask, or if <code>--cifti-output</code> was enabled, all grayordinates. Voxels are grouped into cortical (Ctx GM), subcortical/deep (dGM) gray matter, deep white matter and CSF (dWM+dCSF), shallow white matter and CSF (sWM+sCSF), and cerebellum (Cb).</p>                    <img class="svg-reportlet" src="./figures/sub-10_task-mixedgamblestask_run-1_desc-carpetplot_bold.svg" style="width: 100%" />
 </div>
 <div class="elem-filename">
     Get figure file: <a href="./figures/sub-10_task-mixedgamblestask_run-1_desc-carpetplot_bold.svg" target="_blank">figures/sub-10_task-mixedgamblestask_run-1_desc-carpetplot_bold.svg</a>

fmriprep/interfaces/confounds.py

@@ -507,7 +507,9 @@ def _run_interface(self, runtime):
             nb.load(seg_file),
             remap_rois=False,
             labels=(
-                ("WM+CSF", "Edge") if has_cifti else ("Ctx GM", "dGM", "WM+CSF", "Cb", "Edge")
+                ("WM+CSF", "Edge")
+                if has_cifti
+                else ("Ctx GM", "dGM", "sWM+sCSF", "dWM+dCSF", "Cb", "Edge")
             ),
         )
 

fmriprep/workflows/bold/base.py

@@ -1007,6 +1007,12 @@ def init_func_preproc_wf(bold_file, has_fieldmap=False):
             )
             # fmt:on
 
+        def _last(inlist):
+            return inlist[-1]
+
+        def _last(inlist):
+            return inlist[-1]
+
         # fmt:off
         workflow.connect([
             (initial_boldref_wf, carpetplot_wf, [
@@ -1026,7 +1032,8 @@ def init_func_preproc_wf(bold_file, has_fieldmap=False):
             ]),
             (bold_confounds_wf, carpetplot_wf, [
                 ("outputnode.confounds_file", "inputnode.confounds_file"),
-                ("outputnode.crown_mask", "inputnode.crown_mask")
+                ("outputnode.crown_mask", "inputnode.crown_mask"),
+                (("outputnode.acompcor_masks", _last), "inputnode.acompcor_mask"),
             ]),
         ])
         # fmt:on

fmriprep/workflows/bold/confounds.py

@@ -640,6 +640,8 @@ def init_carpetplot_wf(
         BOLD image in CIFTI format, to be used in place of volumetric BOLD
     crown_mask
         Mask of brain edge voxels
+    acompcor_mask
+        Mask of deep WM+CSF
     dummy_scans
         Number of nonsteady states to be dropped at the beginning of the timeseries.
 
@@ -662,6 +664,7 @@ def init_carpetplot_wf(
                 "std2anat_xfm",
                 "cifti_bold",
                 "crown_mask",
+                "acompcor_mask",
                 "dummy_scans",
             ]
         ),
@@ -728,6 +731,7 @@ def init_carpetplot_wf(
                                ("std2anat_xfm", "in2")]),
         (inputnode, resample_parc, [("bold_mask", "reference_image")]),
         (inputnode, parcels, [("crown_mask", "crown_mask")]),
+        (inputnode, parcels, [("acompcor_mask", "acompcor_mask")]),
         (inputnode, conf_plot, [("bold", "in_nifti"),
                                 ("confounds_file", "confounds_file"),
                                 ("dummy_scans", "drop_trs")]),
@@ -1073,7 +1077,7 @@ def _binary_union(mask1, mask2):
     return str(out_name)
 
 
-def _carpet_parcellation(segmentation, crown_mask, nifti=False):
+def _carpet_parcellation(segmentation, crown_mask, acompcor_mask, nifti=False):
     """Generate the union of two masks."""
     from pathlib import Path
 
@@ -1086,10 +1090,12 @@ def _carpet_parcellation(segmentation, crown_mask, nifti=False):
     lut[100:201] = 1 if nifti else 0  # Ctx GM
     lut[30:99] = 2 if nifti else 0  # dGM
     lut[1:11] = 3 if nifti else 1  # WM+CSF
-    lut[255] = 4 if nifti else 0  # Cerebellum
+    lut[255] = 5 if nifti else 0  # Cerebellum
     # Apply lookup table
-    seg = lut[np.asanyarray(img.dataobj, dtype="uint16")]
-    seg[np.asanyarray(nb.load(crown_mask).dataobj, dtype=int) > 0] = 5 if nifti else 2
+    seg = lut[np.uint16(img.dataobj)]
+    seg[np.bool_(nb.load(crown_mask).dataobj)] = 6 if nifti else 2
+    # Separate deep from shallow WM+CSF
+    seg[np.bool_(nb.load(acompcor_mask).dataobj)] = 4 if nifti else 1
 
     outimg = img.__class__(seg.astype("uint8"), img.affine, img.header)
     outimg.set_data_dtype("uint8")