Merge pull request #2122 from effigies/enh/compcor_exclude

ENH: Allow CompCor to skip initial volumes

Author: effigies

nipype/algorithms/confounds.py

@@ -345,6 +345,9 @@ class CompCorInputSpec(BaseInterfaceInputSpec):
              'unspecified')
     save_pre_filter = traits.Either(
         traits.Bool, File, desc='Save pre-filter basis as text file')
+    ignore_initial_volumes = traits.Range(
+        low=0, usedefault=True,
+        desc='Number of volumes at start of series to ignore')
 
 
 class CompCorOutputSpec(TraitedSpec):
@@ -357,6 +360,26 @@ class CompCor(BaseInterface):
     """
     Interface with core CompCor computation, used in aCompCor and tCompCor
 
+    CompCor provides three pre-filter options, all of which include per-voxel
+    mean removal:
+      - polynomial: Legendre polynomial basis
+      - cosine: Discrete cosine basis
+      - False: mean-removal only
+
+    In the case of ``polynomial`` and ``cosine`` filters, a pre-filter file may
+    be saved with a row for each volume/timepoint, and a column for each
+    non-constant regressor.
+    If no non-constant (mean-removal) columns are used, this file may be empty.
+
+    If ``ignore_initial_volumes`` is set, then the specified number of initial
+    volumes are excluded both from pre-filtering and CompCor component
+    extraction.
+    Each column in the components and pre-filter files are prefixe with zeros
+    for each excluded volume so that the number of rows continues to match the
+    number of volumes in the input file.
+    In addition, for each excluded volume, a column is added to the pre-filter
+    file with a 1 in the corresponding row.
+
     Example
     -------
 
@@ -417,6 +440,12 @@ def _run_interface(self, runtime):
                                  header=imgseries.header)
             mask_images = [img]
 
+        skip_vols = self.inputs.ignore_initial_volumes
+        if skip_vols:
+            imgseries = imgseries.__class__(
+                imgseries.get_data()[..., skip_vols:], imgseries.affine,
+                imgseries.header)
+
         mask_images = self._process_masks(mask_images, imgseries.get_data())
 
         TR = 0
@@ -441,6 +470,13 @@ def _run_interface(self, runtime):
             imgseries.get_data(), mask_images, self.inputs.num_components,
             self.inputs.pre_filter, degree, self.inputs.high_pass_cutoff, TR)
 
+        if skip_vols:
+            old_comp = components
+            nrows = skip_vols + components.shape[0]
+            components = np.zeros((nrows, components.shape[1]),
+                                  dtype=components.dtype)
+            components[skip_vols:] = old_comp
+
         components_file = os.path.join(os.getcwd(), self.inputs.components_file)
         np.savetxt(components_file, components, fmt=b"%.10f", delimiter='\t',
                    header=self._make_headers(components.shape[1]), comments='')
@@ -451,6 +487,15 @@ def _run_interface(self, runtime):
                      'cosine': 'cos'}[self.inputs.pre_filter]
             ncols = filter_basis.shape[1] if filter_basis.size > 0 else 0
             header = ['{}{:02d}'.format(ftype, i) for i in range(ncols)]
+            if skip_vols:
+                old_basis = filter_basis
+                nrows = filter_basis.shape[0] if filter_basis.size > 0 else 0
+                filter_basis = np.zeros((nrows + skip_vols, ncols + skip_vols),
+                                        dtype=filter_basis.dtype)
+                filter_basis[skip_vols:, :ncols] = old_basis
+                filter_basis[:skip_vols, -skip_vols:] = np.eye(skip_vols)
+                header.extend(['SteadyState{:02d}'.format(i)
+                               for i in range(skip_vols)])
             np.savetxt(pre_filter_file, filter_basis, fmt=b'%.10f',
                        delimiter='\t', header='\t'.join(header), comments='')
 

nipype/algorithms/tests/test_auto_ACompCor.py

@@ -12,6 +12,8 @@ def test_ACompCor_inputs():
     ignore_exception=dict(nohash=True,
     usedefault=True,
     ),
+    ignore_initial_volumes=dict(usedefault=True,
+    ),
     mask_files=dict(),
     mask_index=dict(requires=['mask_files'],
     xor=['merge_method'],

nipype/algorithms/tests/test_auto_TCompCor.py

@@ -12,6 +12,8 @@ def test_TCompCor_inputs():
     ignore_exception=dict(nohash=True,
     usedefault=True,
     ),
+    ignore_initial_volumes=dict(usedefault=True,
+    ),
     mask_files=dict(),
     mask_index=dict(requires=['mask_files'],
     xor=['merge_method'],