ENH: Future proof the API for new template building

A) Ants developers are working on a multi-modal
registration extension to antsRegistration to JOINTLY! Register multiple
image modalities while estimating the best transformation.  This is a
great improvement on template building in some cases.

2) The passive images that are part of template building are sometimes
label maps instead of intensity images, in that case, we need to use
Nearest Neighbor instead of the hard-coded linear.

The API change necessary to accomplish both of these task could be done
now, with no behavior benefits at the moment.

B) currently in antsRegistrationBuildTemplate.py:
     inputSpec = pe.Node(interface=util.IdentityInterface(
           fields=['images',
'fixed_image','ListOfPassiveImagesDictionaries']),
           name='InputSpec')
tbuilder.connect(initAvg, 'output_average_image', buildTemplateIteration1,
'InputSpec.fixed_image')
tbuilder.connect(datasource, 'imageList', buildTemplateIteration1,
'InputSpec.images')
tbuilder.connect(datasource, 'passiveImagesDictionariesList',
buildTemplateIteration1, 'InputSpec.ListOfPassiveImagesDictionaries')

C) I propose the following interface perhaps we should implement this now
to avoid API change later:
    inputSpec = pe.Node(interface=util.IdentityInterface(
           fields=['ListOfImagesDictionaries',
'registrationImages','interpolationMap','fixed_image']),
           name='InputSpec')

ListOfImagesDictionaries - a list of dictionaries where each dictionary is
for one scan session, and the mappings in the dictionary are for all the
co-aligned images for that one scan session
[ {'T1':'subj1/T1.nii','T2':'subj1/T2.nii','labelmap':'subj1/labels.nii'},
   {'T1':'subj2/T1.nii','T2':'subj2/T2.nii','labelmap':'subj2/labels.nii'},
   …
   {'T1':'subjN/T1.nii','T2':'subjN/T2.nii','labelmap':'subjN/labels.nii'},

]

registrationImages - A list of the image types to be used actively during
the estimation process of registration, any image type not in this list
will be passively resampled with the estimated transforms.

['T1','T2']

interpolationMap - A map of image types to interpolation modes.  If an
image type is not listed, it will be linearly interpolated.
{ 'labelmap':'NearestNeighbor', 'FLAIR':'WindowedSinc' }

tbuilder.connect(initAvg, 'output_average_image', buildTemplateIteration1,
'InputSpec.fixed_image')
tbuilder.connect(datasource, 'imageList', buildTemplateIteration1,
'InputSpec.images')
tbuilder.connect(datasource, 'passiveImagesDictionariesList',
buildTemplateIteration1, 'InputSpec.ListOfPassiveImagesDictionaries')

input_interpolation_dict={'INV_T1':'Linear','LABEL_MAP':'NearestNeighbor'}

Author: hjmjohnson

examples/smri_ants_build_template_new.py

@@ -53,17 +53,32 @@
     else:
         print("File previously downloaded {0}".format(localFilename))
 
-input_images=[
-os.path.join(mydatadir,'01_T1_half.nii.gz'),
-os.path.join(mydatadir,'02_T1_half.nii.gz'),
-os.path.join(mydatadir,'03_T1_half.nii.gz')
-]
-input_passive_images=[
-{'INV_T1':os.path.join(mydatadir,'01_T1_inv_half.nii.gz')},
-{'INV_T1':os.path.join(mydatadir,'02_T1_inv_half.nii.gz')},
-{'INV_T1':os.path.join(mydatadir,'03_T1_inv_half.nii.gz')}
+
+"""
+ListOfImagesDictionaries - a list of dictionaries where each dictionary is
+for one scan session, and the mappings in the dictionary are for all the
+co-aligned images for that one scan session
+"""
+ListOfImagesDictionaries=[
+{'T1':os.path.join(mydatadir,'01_T1_half.nii.gz'),'INV_T1':os.path.join(mydatadir,'01_T1_inv_half.nii.gz'),'LABEL_MAP':os.path.join(mydatadir,'01_T1_inv_half.nii.gz')},
+{'T1':os.path.join(mydatadir,'02_T1_half.nii.gz'),'INV_T1':os.path.join(mydatadir,'02_T1_inv_half.nii.gz'),'LABEL_MAP':os.path.join(mydatadir,'02_T1_inv_half.nii.gz')},
+{'T1':os.path.join(mydatadir,'03_T1_half.nii.gz'),'INV_T1':os.path.join(mydatadir,'03_T1_inv_half.nii.gz'),'LABEL_MAP':os.path.join(mydatadir,'03_T1_inv_half.nii.gz')}
 ]
 
+"""
+registrationImageTypes - A list of the image types to be used actively during
+the estimation process of registration, any image type not in this list
+will be passively resampled with the estimated transforms.
+['T1','T2']
+"""
+registrationImageTypes=['T1']
+
+"""
+interpolationMap - A map of image types to interpolation modes.  If an
+image type is not listed, it will be linearly interpolated.
+{ 'labelmap':'NearestNeighbor', 'FLAIR':'WindowedSinc' }
+"""
+interpolationMapping={'INV_T1':'LanczosWindowedSinc','LABEL_MAP':'NearestNeighbor','T1':'Linear'}
 
 """
 3. Define the workflow and its working directory
@@ -74,44 +89,50 @@
 """
 4. Define data sources. In real life these would be replace by DataGrabbers
 """
+InitialTemplateInputs=[ mdict['T1'] for mdict in ListOfImagesDictionaries ]
+
 datasource = pe.Node(interface=util.IdentityInterface(fields=
-                    ['imageList', 'passiveImagesDictionariesList']),
+                    ['InitialTemplateInputs', 'ListOfImagesDictionaries',
+                     'registrationImageTypes','interpolationMapping']),
                     run_without_submitting=True,
                     name='InputImages' )
-datasource.inputs.imageList=input_images
-datasource.inputs.passiveImagesDictionariesList=input_passive_images
+datasource.inputs.InitialTemplateInputs=InitialTemplateInputs
+datasource.inputs.ListOfImagesDictionaries=ListOfImagesDictionaries
+datasource.inputs.registrationImageTypes=registrationImageTypes
+datasource.inputs.interpolationMapping=interpolationMapping
 
 """
-5. Template is initialized by a simple average
+5. Template is initialized by a simple average in this simple example,
+   any reference image could be used (i.e. a previously created template)
 """
 initAvg = pe.Node(interface=ants.AverageImages(), name ='initAvg')
 initAvg.inputs.dimension = 3
 initAvg.inputs.normalize = True
 
-tbuilder.connect(datasource, "imageList", initAvg, "images")
+tbuilder.connect(datasource, "InitialTemplateInputs", initAvg, "images")
 
 """
 6. Define the first iteration of template building
 """
 
 buildTemplateIteration1=antsRegistrationTemplateBuildSingleIterationWF('iteration01')
 tbuilder.connect(initAvg, 'output_average_image', buildTemplateIteration1, 'InputSpec.fixed_image')
-tbuilder.connect(datasource, 'imageList', buildTemplateIteration1, 'InputSpec.images')
-tbuilder.connect(datasource, 'passiveImagesDictionariesList', buildTemplateIteration1, 'InputSpec.ListOfPassiveImagesDictionaries')
+tbuilder.connect(datasource, 'ListOfImagesDictionaries', buildTemplateIteration1, 'InputSpec.ListOfImagesDictionaries')
+tbuilder.connect(datasource, 'registrationImageTypes', buildTemplateIteration1, 'InputSpec.registrationImageTypes')
+tbuilder.connect(datasource, 'interpolationMapping', buildTemplateIteration1, 'InputSpec.interpolationMapping')
 
 """
 7. Define the second iteration of template building
 """
-
 buildTemplateIteration2 = antsRegistrationTemplateBuildSingleIterationWF('iteration02')
 tbuilder.connect(buildTemplateIteration1, 'OutputSpec.template', buildTemplateIteration2, 'InputSpec.fixed_image')
-tbuilder.connect(datasource, 'imageList', buildTemplateIteration2, 'InputSpec.images')
-tbuilder.connect(datasource, 'passiveImagesDictionariesList', buildTemplateIteration2, 'InputSpec.ListOfPassiveImagesDictionaries')
+tbuilder.connect(datasource, 'ListOfImagesDictionaries', buildTemplateIteration2, 'InputSpec.ListOfImagesDictionaries')
+tbuilder.connect(datasource, 'registrationImageTypes', buildTemplateIteration2, 'InputSpec.registrationImageTypes')
+tbuilder.connect(datasource, 'interpolationMapping', buildTemplateIteration2, 'InputSpec.interpolationMapping')
 
 """
 8. Move selected files to a designated results folder
 """
-
 datasink = pe.Node(io.DataSink(), name="datasink")
 datasink.inputs.base_directory = os.path.join(requestedPath, "results")
 

examples/smri_ants_registration.py

@@ -72,8 +72,8 @@
 reg.inputs.shrink_factors = [[2,1], [3,2,1]]
 reg.inputs.use_estimate_learning_rate_once = [True, True]
 reg.inputs.use_histogram_matching = [True, True] # This is the default
-reg.inputs.output_transform_prefix = "t1_average_BRAINSABC_To_template_t1_clipped"
-reg.inputs.output_warped_image = 't1_average_BRAINSABC_To_template_t1_clipped_INTERNAL_WARPED.nii.gz'
+reg.inputs.output_transform_prefix = 'thisTransform'
+reg.inputs.output_warped_image = 'INTERNAL_WARPED.nii.gz'
 reg.cmdline
 
 

nipype/interfaces/ants/registration.py

@@ -193,6 +193,17 @@ class RegistrationInputSpec(ANTSCommandInputSpec):
 
     use_estimate_learning_rate_once = traits.List(traits.Bool(), desc='')
     use_histogram_matching = traits.List(traits.Bool(argstr='%s'), default=True, usedefault=True)
+    # Interpolation flag
+    interpolation = traits.Enum('Linear',
+                                'NearestNeighbor',
+                                'CosineWindowedSinc',
+                                'WelchWindowedSinc',
+                                'HammingWindowedSinc',
+                                'LanczosWindowedSinc',
+                                # 'MultiLabel',
+                                # 'Gaussian',
+                                # 'BSpline',
+                                argstr='%s', usedefault = True)
     # Transform flags
     write_composite_transform = traits.Bool(argstr='--write-composite-transform %d', default=False, usedefault=True, desc='')
     transforms = traits.List(traits.Enum('Rigid', 'Affine', 'CompositeAffine',
@@ -324,6 +335,9 @@ def _format_arg(self, opt, spec, val):
                 return '--initial-moving-transform [ %s, 1 ]' % self.inputs.initial_moving_transform
             else:
                 return '--initial-moving-transform [ %s, 0 ]' % self.inputs.initial_moving_transform
+        elif opt == 'interpolation':
+            # TODO: handle multilabel, gaussian, and bspline options
+            return '--interpolation %s' % self.inputs.interpolation
         elif opt == 'output_transform_prefix':
             if isdefined(self.inputs.output_inverse_warped_image) and self.inputs.output_inverse_warped_image:
                 return '--output [ %s, %s, %s ]' % (self.inputs.output_transform_prefix, self.inputs.output_warped_image, self.inputs.output_inverse_warped_image )