BUG: Restore registration interface failed multi-modal

Registration interface was failing to support
multimodal input when they are given.

ex)
nipype:
  antsWF.inputs.fixed_image=['fixed_t1.nii.gz',
                             'fixed_t2.nii.gz']
  antsWF.inputs.moving_image=['moving_t1.nii.gz',
                              'moving_t2.nii.gz']

corresponding correct commandline:
  --metric MI[\
      fixed_t1.nii.gz,\
      moving_t1.nii.gz,\ ...
  --metric MI[\
    fixed_t2.nii.gz,\
    moving_t2.nii.gz,\ ...

Modifed test to be more clear about the multi-modal state.
Modifed example to be more realistic use of metrics.
Added comments to improve how metrics are used.

Reported in issue: #1175

Author: hjmjohnson

CHANGES

@@ -1,6 +1,8 @@
 Next release
 ============
 
+* BUG: ANTs Registration interface failed with multi-modal inputs
+    (https://github.com/nipy/nipype/pull/1176) (https://github.com/nipy/nipype/issues/1175)
 * FIX: Bug in XFibres5 (https://github.com/nipy/nipype/pull/1168)
 * ENH: Attempt to use hard links for data sink.
     (https://github.com/nipy/nipype/pull/1161)

nipype/interfaces/ants/registration.py

@@ -26,6 +26,26 @@ class ANTSInputSpec(ANTSCommandInputSpec):
                                   desc=('image to apply transformation to (generally a coregistered '
                                         'functional)'))
 
+#    Not all metrics are appropriate for all modalities. Also, not all metrics
+#    are efficeint or appropriate at all resolution levels, Some metrics perform
+#    well for gross global registraiton, but do poorly for small changes (i.e.
+#    Mattes), and some metrics do well for small changes but don't work well for
+#    gross level changes (i.e. 'CC').
+#
+#    This is a two stage registration. in the first stage
+#      [ 'Mattes', .................]
+#         ^^^^^^ <- First stage
+#    Do a unimodal registration of the first elements of the fixed/moving input
+#    list use the"CC" as the metric.
+#
+#    In the second stage
+#      [ ....., ['Mattes','CC'] ]
+#               ^^^^^^^^^^^^^^^ <- Second stage
+#    Do a multi-modal registration where the first elements of fixed/moving
+#    input list use 'CC' metric and that is added to 'Mattes' metric result of
+#    the second elements of the fixed/moving input.
+#
+#    Cost = Sum_i ( metricweight[i] Metric_i ( fixedimage[i], movingimage[i]) )
     metric = traits.List(traits.Enum('CC', 'MI', 'SMI', 'PR', 'SSD',
                          'MSQ', 'PSE'), mandatory=True, desc='')
 
@@ -440,13 +460,15 @@ class Registration(ANTSCommand):
 
     >>> # Test multiple metrics per stage
     >>> reg5 = copy.deepcopy(reg)
-    >>> reg5.inputs.metric = ['CC', ['CC', 'Mattes']]
-    >>> reg5.inputs.metric_weight = [1, [.5]*2]
-    >>> reg5.inputs.radius_or_number_of_bins = [4, [32]*2]
+    >>> reg5.inputs.fixed_image = [ 'fixed1.nii', 'fixed2.nii' ]
+    >>> reg5.inputs.moving_image = [ 'moving1.nii', 'moving2.nii' ]
+    >>> reg5.inputs.metric = ['Mattes', ['Mattes', 'CC']]
+    >>> reg5.inputs.metric_weight = [1, [.5,.5]]
+    >>> reg5.inputs.radius_or_number_of_bins = [32, [32,4] ]
     >>> reg5.inputs.sampling_strategy = ['Random', None] # use default strategy in second stage
     >>> reg5.inputs.sampling_percentage = [0.05, [0.05, 0.10]]
     >>> reg5.cmdline
-    '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 ] --restore-state trans.mat --save-state trans.mat --transform Affine[ 2.0 ] --metric CC[ fixed1.nii, moving1.nii, 1, 4, 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 --transform SyN[ 0.25, 3.0, 0.0 ] --metric CC[ fixed1.nii, moving1.nii, 0.5, 32, None, 0.05 ] --metric Mattes[ fixed1.nii, moving1.nii, 0.5, 32, None, 0.1 ] --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'
+    '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 ] --restore-state trans.mat --save-state trans.mat --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 --transform SyN[ 0.25, 3.0, 0.0 ] --metric Mattes[ fixed1.nii, moving1.nii, 0.5, 32, None, 0.05 ] --metric CC[ fixed2.nii, moving2.nii, 0.5, 4, None, 0.1 ] --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'
     """
     DEF_SAMPLING_STRATEGY = 'None'
     """The default sampling strategy argument."""
@@ -466,14 +488,12 @@ def _formatMetric(self, index):
         ----------
         index: the stage index
         """
-        # The common fixed image.
-        fixed = self.inputs.fixed_image[0]
-        # The common moving image.
-        moving = self.inputs.moving_image[0]
         # The metric name input for the current stage.
         name_input = self.inputs.metric[index]
         # The stage-specific input dictionary.
         stage_inputs = dict(
+            fixed_image=self.inputs.fixed_image[0],
+            moving_image=self.inputs.moving_image[0],
             metric=name_input,
             weight=self.inputs.metric_weight[index],
             radius_or_bins=self.inputs.radius_or_number_of_bins[index],
@@ -499,19 +519,32 @@ def _formatMetric(self, index):
         if isinstance(name_input, list):
             items = stage_inputs.items()
             indexes = range(0, len(name_input))
-            # dict-comprehension only works with python 2.7 and up
-            #specs = [{k: v[i] for k, v in items} for i in indexes]
-            specs = [dict([(k, v[i]) for k, v in items]) for i in indexes]
+            specs = list()
+            for i in indexes:
+                temp = dict([(k, v[i]) for k, v in items])
+                if i > len( self.inputs.fixed_image ):
+                    temp["fixed_image"] = self.inputs.fixed_image[0]
+                else:
+                    temp["fixed_image"] = self.inputs.fixed_image[i]
+
+                if i > len( self.inputs.moving_image ):
+                    temp["moving_image"] = self.inputs.moving_image[0]
+                else:
+                    temp["moving_image"] = self.inputs.moving_image[i]
+
+                specs.append( temp )
         else:
             specs = [stage_inputs]
 
         # Format the --metric command line metric arguments, one per
         # specification.
-        return [self._formatMetricArgument(fixed, moving, **spec) for spec in specs]
+        return [self._formatMetricArgument(**spec) for spec in specs]
 
-    def _formatMetricArgument(self, fixed, moving, **kwargs):
+    def _formatMetricArgument(self, **kwargs):
         retval = '%s[ %s, %s, %g, %d' % (kwargs['metric'],
-                                         fixed, moving, kwargs['weight'],
+                                         kwargs['fixed_image'],
+                                         kwargs['moving_image'],
+                                         kwargs['weight'],
                                          kwargs['radius_or_bins'])
 
         # The optional sampling strategy.