ENH: Enable antsRegistration 2.2.0+ masking

Author: effigies

nipype/interfaces/ants/registration.py

@@ -11,6 +11,7 @@
 from builtins import range, str
 import os
 
+from ...utils.filemanip import filename_to_list
 from ..base import TraitedSpec, File, Str, traits, InputMultiPath, isdefined
 from .base import ANTSCommand, ANTSCommandInputSpec
 
@@ -219,12 +220,22 @@ class RegistrationInputSpec(ANTSCommandInputSpec):
                             usedefault=True, desc='image dimension (2 or 3)')
     fixed_image = InputMultiPath(File(exists=True), mandatory=True,
                                  desc='image to apply transformation to (generally a coregistered functional)')
-    fixed_image_mask = File(argstr='%s', exists=True,
-                            desc='mask used to limit metric sampling region of the fixed image')
+    fixed_image_mask = File(
+        exists=True, argstr='%s', max_ver='2.1.0', xor=['fixed_image_masks'],
+        desc='mask used to limit metric sampling region of the fixed image')
+    fixed_image_masks = InputMultiPath(
+        traits.Either('NULL', File(exists=True)), min_ver='2.2.0', xor=['fixed_image_mask'],
+        desc='mask used to limit metric sampling region of the fixed image '
+        '(Use "NULL" to omit a mask at a given stage)')
     moving_image = InputMultiPath(File(exists=True), mandatory=True,
                                   desc='image to apply transformation to (generally a coregistered functional)')
-    moving_image_mask = File(requires=['fixed_image_mask'],
-                             exists=True, desc='mask used to limit metric sampling region of the moving image')
+    moving_image_mask = File(
+        exists=True, requires=['fixed_image_mask'], max_ver='2.1.0', xor=['moving_image_masks'],
+        desc='mask used to limit metric sampling region of the moving image')
+    moving_image_masks = InputMultiPath(
+        traits.Either('NULL', File(exists=True)), min_ver='2.2.0', xor=['moving_image_mask'],
+        desc='mask used to limit metric sampling region of the moving image '
+        '(Use "NULL" to omit a mask at a given stage)')
 
     save_state = File(argstr='--save-state %s', exists=False,
                       desc='Filename for saving the internal restorable state of the registration')
@@ -648,6 +659,20 @@ class Registration(ANTSCommand):
 --metric Mattes[ fixed1.nii, moving1.nii, 1, 32 ] --convergence [ 100x50x30, 1e-09, 20 ] \
 --smoothing-sigmas 2.0x1.0x0.0vox --shrink-factors 3x2x1 --use-estimate-learning-rate-once 1 \
 --use-histogram-matching 1 --winsorize-image-intensities [ 0.0, 1.0 ]  --write-composite-transform 1'
+
+    >>> # Test masking
+    >>> reg9 = copy.deepcopy(reg)
+    >>> reg9.inputs.fixed_image_masks = ['NULL', 'fixed1.nii']
+    >>> reg9.cmdline # doctest: +ALLOW_UNICODE
+    'antsRegistration --collapse-output-transforms 0 --dimensionality 3 --initial-moving-transform [ trans.mat, 1 ] \
+--initialize-transforms-per-stage 0 --interpolation Linear --output [ output_, output_warped_image.nii.gz ] \
+--transform Affine[ 2.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32, Random, 0.05 ] \
+--convergence [ 1500x200, 1e-08, 20 ] --smoothing-sigmas 1.0x0.0vox --shrink-factors 2x1 \
+--use-estimate-learning-rate-once 1 --use-histogram-matching 1 --masks [ NULL, NULL ] \
+--transform SyN[ 0.25, 3.0, 0.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 1, 32 ] \
+--convergence [ 100x50x30, 1e-09, 20 ] --smoothing-sigmas 2.0x1.0x0.0vox --shrink-factors 3x2x1 \
+--use-estimate-learning-rate-once 1 --use-histogram-matching 1 --masks [ fixed1.nii, NULL ] \
+--winsorize-image-intensities [ 0.0, 1.0 ]  --write-composite-transform 1'
     """
     DEF_SAMPLING_STRATEGY = 'None'
     """The default sampling strategy argument."""
@@ -783,6 +808,20 @@ def _format_registration(self):
             if isdefined(self.inputs.restrict_deformation):
                 retval.append('--restrict-deformation %s' %
                               self._format_xarray(self.inputs.restrict_deformation[ii]))
+            if any((isdefined(self.inputs.fixed_image_masks),
+                    isdefined(self.inputs.moving_image_masks))):
+                if isdefined(self.inputs.fixed_image_masks):
+                    fixed_masks = filename_to_list(self.inputs.fixed_image_masks)
+                    fixed_mask = fixed_masks[ii if len(fixed_masks) > 1 else 0]
+                else:
+                    fixed_mask = 'NULL'
+
+                if isdefined(self.inputs.moving_image_masks):
+                    moving_masks = filename_to_list(self.inputs.moving_image_masks)
+                    moving_mask = moving_masks[ii if len(moving_masks) > 1 else 0]
+                else:
+                    moving_mask = 'NULL'
+                retval.append('--masks [ %s, %s ]' % (fixed_mask, moving_mask))
         return " ".join(retval)
 
     def _get_outputfilenames(self, inverse=False):

nipype/interfaces/ants/tests/test_auto_Registration.py

@@ -24,6 +24,11 @@ def test_Registration_inputs():
     fixed_image=dict(mandatory=True,
     ),
     fixed_image_mask=dict(argstr='%s',
+    max_ver='2.1.0',
+    xor=['fixed_image_masks'],
+    ),
+    fixed_image_masks=dict(min_ver='2.2.0',
+    xor=['fixed_image_mask'],
     ),
     float=dict(argstr='--float %d',
     ),
@@ -58,7 +63,12 @@ def test_Registration_inputs():
     metric_weight_stage_trait=dict(),
     moving_image=dict(mandatory=True,
     ),
-    moving_image_mask=dict(requires=['fixed_image_mask'],
+    moving_image_mask=dict(max_ver='2.1.0',
+    requires=['fixed_image_mask'],
+    xor=['moving_image_masks'],
+    ),
+    moving_image_masks=dict(min_ver='2.2.0',
+    xor=['moving_image_mask'],
     ),
     num_threads=dict(nohash=True,
     usedefault=True,