Merge branch 'antsJointFusionWrapper' of https://github.com/BRAINSia/nipype into BRAINSia-antsJointFusionWrapper

Author: chrisgorgo

CHANGES

@@ -3,6 +3,7 @@ Next release
 
 * ENH: Added interfaces of AFNI (https://github.com/nipy/nipype/pull/1360,
        https://github.com/nipy/nipype/pull/1361)
+* ENH: Provides a Nipype wrapper for antsJointFusion (https://github.com/nipy/nipype/pull/1351)
 * ENH: Added support for PETPVC (https://github.com/nipy/nipype/pull/1335)
 * ENH: Merge S3DataSink into DataSink, added AWS documentation (https://github.com/nipy/nipype/pull/1316)
 * TST: Cache APT in CircleCI (https://github.com/nipy/nipype/pull/1333)

nipype/interfaces/ants/__init__.py

@@ -12,7 +12,7 @@
 
 # Segmentation Programs
 from .segmentation import (Atropos, LaplacianThickness, N4BiasFieldCorrection, JointFusion, CorticalThickness,
-                           BrainExtraction, DenoiseImage)
+                           BrainExtraction, DenoiseImage, AntsJointFusion)
 
 # Visualization Programs
 from .visualization import ConvertScalarImageToRGB, CreateTiledMosaic

nipype/interfaces/ants/segmentation.py

@@ -869,3 +869,201 @@ def _format_arg(self, name, trait_spec, value):
 
         return super(DenoiseImage,
                      self)._format_arg(name, trait_spec, value)
+
+
+class AntsJointFusionInputSpec(ANTSCommandInputSpec):
+    dimension = traits.Enum(3, 2, 4, argstr='-d %d', usedefault=False,
+                            desc='This option forces the image to be treated '
+                                 'as a specified-dimensional image. If not '
+                                 'specified, the program tries to infer the '
+                                 'dimensionality from the input image.')
+    target_image = traits.List(InputMultiPath(File(exists=True)), argstr='-t %s',
+                                  mandatory=True, desc='The target image (or '
+                                  'multimodal target images) assumed to be '
+                                  'aligned to a common image domain.')
+    atlas_image = traits.List(InputMultiPath(File(exists=True)), argstr="-g %s...",
+                                 mandatory=True, desc='The atlas image (or '
+                                 'multimodal atlas images) assumed to be '
+                                 'aligned to a common image domain.')
+    atlas_segmentation_image = InputMultiPath(File(exists=True), argstr="-l %s...",
+                                  mandatory=True, desc='The atlas segmentation '
+                                  'images. For performing label fusion the number '
+                                  'of specified segmentations should be identical '
+                                  'to the number of atlas image sets.')
+    alpha = traits.Float(default_value=0.1, usedefault=True, argstr='-a %s', desc=('Regularization '
+                         'term added to matrix Mx for calculating the inverse. Default = 0.1'))
+    beta = traits.Float(default_value=2.0, usedefault=True, argstr='-b %s', desc=('Exponent for mapping '
+                      'intensity difference to the joint error. Default = 2.0'))
+    retain_label_posterior_images = traits.Bool(False, argstr='-r', usedefault=True,
+                         requires=['atlas_segmentation_image'],
+                         desc=('Retain label posterior probability images. Requires '
+                               'atlas segmentations to be specified. Default = false'))
+    retain_atlas_voting_images = traits.Bool(False, argstr='-f', usedefault=True,
+                         desc=('Retain atlas voting images. Default = false'))
+    constrain_nonnegative = traits.Bool(False, argstr='-c', usedefault=True,
+                         desc=('Constrain solution to non-negative weights.'))
+    patch_radius = traits.ListInt(minlen=3, maxlen=3, argstr='-p %s',
+                                  desc=('Patch radius for similarity measures.'
+                                        'Default: 2x2x2'))
+    patch_metric = traits.Enum('PC', 'MSQ', argstr='-m %s', usedefault=False,
+                        desc=('Metric to be used in determining the most similar '
+                              'neighborhood patch. Options include Pearson\'s '
+                              'correlation (PC) and mean squares (MSQ). Default = '
+                              'PC (Pearson correlation).'))
+    search_radius = traits.List([3,3,3], minlen=1, maxlen=3, argstr='-s %s', usedefault=True,
+                                   desc=('Search radius for similarity measures. Default = 3x3x3. '
+                                         'One can also specify an image where the value at the '
+                                         'voxel specifies the isotropic search radius at that voxel.'))
+    exclusion_image_label = traits.List(traits.Str(), argstr='-e %s', requires=['exclusion_image'],
+                                       desc=('Specify a label for the exclusion region.'))
+    exclusion_image = traits.List(File(exists=True),
+                                  desc=('Specify an exclusion region for the given label.'))
+    mask_image = File(argstr='-x %s', exists=True, desc='If a mask image '
+                      'is specified, fusion is only performed in the mask region.')
+    out_label_fusion = File(argstr="%s", hash_files=False,
+                            desc='The output label fusion image.')
+    out_intensity_fusion_name_format = traits.Str('antsJointFusionIntensity_%d.nii.gz',
+                                                  argstr="", desc='Optional intensity fusion '
+                                                                  'image file name format.')
+    out_label_post_prob_name_format = traits.Str('antsJointFusionPosterior_%d.nii.gz',
+                                                 requires=['out_label_fusion',
+                                                           'out_intensity_fusion_name_format'],
+                                                 desc='Optional label posterior probability '
+                                                      'image file name format.')
+    out_atlas_voting_weight_name_format = traits.Str('antsJointFusionVotingWeight_%d.nii.gz',
+                                                     requires=['out_label_fusion',
+                                                               'out_intensity_fusion_name_format',
+                                                               'out_label_post_prob_name_format'],
+                                                     desc='Optional atlas voting weight image '
+                                                          'file name format.')
+    verbose = traits.Bool(False, argstr="-v", desc=('Verbose output.'))
+
+
+class AntsJointFusionOutputSpec(TraitedSpec):
+    out_label_fusion = File(exists=True)
+    out_intensity_fusion_name_format = traits.Str()
+    out_label_post_prob_name_format = traits.Str()
+    out_atlas_voting_weight_name_format = traits.Str()
+
+
+class AntsJointFusion(ANTSCommand):
+    """
+    Examples
+    --------
+
+    >>> from nipype.interfaces.ants import AntsJointFusion
+    >>> antsjointfusion = AntsJointFusion()
+    >>> antsjointfusion.inputs.out_label_fusion = 'ants_fusion_label_output.nii'
+    >>> antsjointfusion.inputs.atlas_image = [ ['rc1s1.nii','rc1s2.nii'] ]
+    >>> antsjointfusion.inputs.atlas_segmentation_image = ['segmentation0.nii.gz']
+    >>> antsjointfusion.inputs.target_image = ['im1.nii']
+    >>> antsjointfusion.cmdline
+    "antsJointFusion -a 0.1 -g ['rc1s1.nii', 'rc1s2.nii'] -l segmentation0.nii.gz \
+-b 2.0 -o ants_fusion_label_output.nii -s 3x3x3 -t ['im1.nii']"
+
+    >>> antsjointfusion.inputs.target_image = [ ['im1.nii', 'im2.nii'] ]
+    >>> antsjointfusion.cmdline
+    "antsJointFusion -a 0.1 -g ['rc1s1.nii', 'rc1s2.nii'] -l segmentation0.nii.gz \
+-b 2.0 -o ants_fusion_label_output.nii -s 3x3x3 -t ['im1.nii', 'im2.nii']"
+
+    >>> antsjointfusion.inputs.atlas_image = [ ['rc1s1.nii','rc1s2.nii'],
+    ...                                        ['rc2s1.nii','rc2s2.nii'] ]
+    >>> antsjointfusion.inputs.atlas_segmentation_image = ['segmentation0.nii.gz',
+    ...                                                    'segmentation1.nii.gz']
+    >>> antsjointfusion.cmdline
+    "antsJointFusion -a 0.1 -g ['rc1s1.nii', 'rc1s2.nii'] -g ['rc2s1.nii', 'rc2s2.nii'] \
+-l segmentation0.nii.gz -l segmentation1.nii.gz -b 2.0 -o ants_fusion_label_output.nii \
+-s 3x3x3 -t ['im1.nii', 'im2.nii']"
+
+    >>> antsjointfusion.inputs.dimension = 3
+    >>> antsjointfusion.inputs.alpha = 0.5
+    >>> antsjointfusion.inputs.beta = 1.0
+    >>> antsjointfusion.inputs.patch_radius = [3,2,1]
+    >>> antsjointfusion.inputs.search_radius = [3]
+    >>> antsjointfusion.cmdline
+    "antsJointFusion -a 0.5 -g ['rc1s1.nii', 'rc1s2.nii'] -g ['rc2s1.nii', 'rc2s2.nii'] \
+-l segmentation0.nii.gz -l segmentation1.nii.gz -b 1.0 -d 3 -o ants_fusion_label_output.nii \
+-p 3x2x1 -s 3 -t ['im1.nii', 'im2.nii']"
+
+    >>> antsjointfusion.inputs.search_radius = ['mask.nii']
+    >>> antsjointfusion.inputs.verbose = True
+    >>> antsjointfusion.inputs.exclusion_image = ['roi01.nii', 'roi02.nii']
+    >>> antsjointfusion.inputs.exclusion_image_label = ['1','2']
+    >>> antsjointfusion.cmdline
+    "antsJointFusion -a 0.5 -g ['rc1s1.nii', 'rc1s2.nii'] -g ['rc2s1.nii', 'rc2s2.nii'] \
+-l segmentation0.nii.gz -l segmentation1.nii.gz -b 1.0 -d 3 -e 1[roi01.nii] -e 2[roi02.nii] \
+-o ants_fusion_label_output.nii -p 3x2x1 -s mask.nii -t ['im1.nii', 'im2.nii'] -v"
+
+    >>> antsjointfusion.inputs.out_label_fusion = 'ants_fusion_label_output.nii'
+    >>> antsjointfusion.inputs.out_intensity_fusion_name_format = 'ants_joint_fusion_intensity_%d.nii.gz'
+    >>> antsjointfusion.inputs.out_label_post_prob_name_format = 'ants_joint_fusion_posterior_%d.nii.gz'
+    >>> antsjointfusion.inputs.out_atlas_voting_weight_name_format = 'ants_joint_fusion_voting_weight_%d.nii.gz'
+    >>> antsjointfusion.cmdline
+    "antsJointFusion -a 0.5 -g ['rc1s1.nii', 'rc1s2.nii'] -g ['rc2s1.nii', 'rc2s2.nii'] \
+-l segmentation0.nii.gz -l segmentation1.nii.gz -b 1.0 -d 3 -e 1[roi01.nii] -e 2[roi02.nii]  \
+-o [ants_fusion_label_output.nii, ants_joint_fusion_intensity_%d.nii.gz, \
+ants_joint_fusion_posterior_%d.nii.gz, ants_joint_fusion_voting_weight_%d.nii.gz] \
+-p 3x2x1 -s mask.nii -t ['im1.nii', 'im2.nii'] -v"
+
+    """
+    input_spec = AntsJointFusionInputSpec
+    output_spec = AntsJointFusionOutputSpec
+    _cmd = 'antsJointFusion'
+
+    def _format_arg(self, opt, spec, val):
+        if opt == 'exclusion_image_label':
+            retval = []
+            for ii in range(len(self.inputs.exclusion_image_label)):
+                retval.append('-e {0}[{1}]'.format(
+                    self.inputs.exclusion_image_label[ii],
+                    self.inputs.exclusion_image[ii]))
+            retval = ' '.join(retval)
+        elif opt == 'patch_radius':
+            retval = '-p {0}'.format(self._format_xarray(val))
+        elif opt == 'search_radius':
+            retval = '-s {0}'.format(self._format_xarray(val))
+        elif opt == 'out_label_fusion':
+            if isdefined(self.inputs.out_intensity_fusion_name_format):
+                if isdefined(self.inputs.out_label_post_prob_name_format):
+                    if isdefined(self.inputs.out_atlas_voting_weight_name_format):
+                        retval = '-o [{0}, {1}, {2}, {3}]'.format(self.inputs.out_label_fusion,
+                                                self.inputs.out_intensity_fusion_name_format,
+                                                self.inputs.out_label_post_prob_name_format,
+                                                self.inputs.out_atlas_voting_weight_name_format)
+                    else:
+                        retval = '-o [{0}, {1}, {2}]'.format(self.inputs.out_label_fusion,
+                                                self.inputs.out_intensity_fusion_name_format,
+                                                self.inputs.out_label_post_prob_name_format)
+                else:
+                    retval = '-o [{0}, {1}]'.format(self.inputs.out_label_fusion,
+                                                self.inputs.out_intensity_fusion_name_format)
+            else:
+                retval = '-o {0}'.format(self.inputs.out_label_fusion)
+        elif opt == 'out_intensity_fusion_name_format':
+            retval = ''
+            if not isdefined(self.inputs.out_label_fusion):
+                retval = '-o {0}'.format(self.inputs.out_intensity_fusion_name_format)
+        else:
+            if opt == 'atlas_segmentation_image':
+                assert len(val) == len(self.inputs.atlas_image), "Number of specified " \
+                    "segmentations should be identical to the number of atlas image " \
+                    "sets {0}!={1}".format(len(val), len(self.inputs.atlas_image))
+            return super(ANTSCommand, self)._format_arg(opt, spec, val)
+        return retval
+
+    def _list_outputs(self):
+        outputs = self._outputs().get()
+        if isdefined(self.inputs.out_label_fusion):
+            outputs['out_label_fusion'] = os.path.abspath(
+                self.inputs.out_label_fusion)
+        if isdefined(self.inputs.out_intensity_fusion_name_format):
+            outputs['out_intensity_fusion_name_format'] = os.path.abspath(
+                self.inputs.out_intensity_fusion_name_format)
+        if isdefined(self.inputs.out_label_post_prob_name_format):
+            outputs['out_label_post_prob_name_format'] = os.path.abspath(
+                self.inputs.out_label_post_prob_name_format)
+        if isdefined(self.inputs.out_atlas_voting_weight_name_format):
+            outputs['out_atlas_voting_weight_name_format'] = os.path.abspath(
+                self.inputs.out_atlas_voting_weight_name_format)
+
+        return outputs

nipype/interfaces/ants/tests/test_auto_AntsJointFusion.py

@@ -0,0 +1,93 @@
+# AUTO-GENERATED by tools/checkspecs.py - DO NOT EDIT
+from ....testing import assert_equal
+from ..segmentation import AntsJointFusion
+
+
+def test_AntsJointFusion_inputs():
+    input_map = dict(alpha=dict(argstr='-a %s',
+    usedefault=True,
+    ),
+    args=dict(argstr='%s',
+    ),
+    atlas_image=dict(argstr='-g %s...',
+    mandatory=True,
+    ),
+    atlas_segmentation_image=dict(argstr='-l %s...',
+    mandatory=True,
+    ),
+    beta=dict(argstr='-b %s',
+    usedefault=True,
+    ),
+    constrain_nonnegative=dict(argstr='-c',
+    usedefault=True,
+    ),
+    dimension=dict(argstr='-d %d',
+    usedefault=False,
+    ),
+    environ=dict(nohash=True,
+    usedefault=True,
+    ),
+    exclusion_image=dict(),
+    exclusion_image_label=dict(argstr='-e %s',
+    requires=['exclusion_image'],
+    ),
+    ignore_exception=dict(nohash=True,
+    usedefault=True,
+    ),
+    mask_image=dict(argstr='-x %s',
+    ),
+    num_threads=dict(nohash=True,
+    usedefault=True,
+    ),
+    out_atlas_voting_weight_name_format=dict(requires=['out_label_fusion', 'out_intensity_fusion_name_format', 'out_label_post_prob_name_format'],
+    ),
+    out_intensity_fusion_name_format=dict(argstr='',
+    ),
+    out_label_fusion=dict(argstr='%s',
+    hash_files=False,
+    ),
+    out_label_post_prob_name_format=dict(requires=['out_label_fusion', 'out_intensity_fusion_name_format'],
+    ),
+    patch_metric=dict(argstr='-m %s',
+    usedefault=False,
+    ),
+    patch_radius=dict(argstr='-p %s',
+    maxlen=3,
+    minlen=3,
+    ),
+    retain_atlas_voting_images=dict(argstr='-f',
+    usedefault=True,
+    ),
+    retain_label_posterior_images=dict(argstr='-r',
+    requires=['atlas_segmentation_image'],
+    usedefault=True,
+    ),
+    search_radius=dict(argstr='-s %s',
+    usedefault=True,
+    ),
+    target_image=dict(argstr='-t %s',
+    mandatory=True,
+    ),
+    terminal_output=dict(nohash=True,
+    ),
+    verbose=dict(argstr='-v',
+    ),
+    )
+    inputs = AntsJointFusion.input_spec()
+
+    for key, metadata in list(input_map.items()):
+        for metakey, value in list(metadata.items()):
+            yield assert_equal, getattr(inputs.traits()[key], metakey), value
+
+
+def test_AntsJointFusion_outputs():
+    output_map = dict(out_atlas_voting_weight_name_format=dict(),
+    out_intensity_fusion_name_format=dict(),
+    out_label_fusion=dict(),
+    out_label_post_prob_name_format=dict(),
+    )
+    outputs = AntsJointFusion.output_spec()
+
+    for key, metadata in list(output_map.items()):
+        for metakey, value in list(metadata.items()):
+            yield assert_equal, getattr(outputs.traits()[key], metakey), value