Merge branch 'enh/Similarity4DMetrics' into enh/EvaluationAlgorithms

Conflicts:
	CHANGES

Author: oesteban

CHANGES

@@ -2,6 +2,8 @@ Next Release
 ============
 
 * API: Interfaces to external packages are no longer available in the top-level ``nipype`` namespace, and must be imported directly (e.g. ``from nipype.interfaces import fsl``).
+* ENH: nipy.utils.Similarity has been deprecated by algorithms.metrics.Similarity
+       which is an extension of the former to allow 4D images.
 * ENH: New ANTs interface: ApplyTransformsToPoints
 * ENH: New metrics group in algorithms. Now Distance, Overlap, and FuzzyOverlap
        are found in nipype.algorithms.metrics instead of misc

nipype/algorithms/metrics.py

@@ -495,3 +495,93 @@ def _list_outputs(self):
         outputs['out_map'] = self._out_file
 
         return outputs
+
+
+class SimilarityInputSpec(BaseInterfaceInputSpec):
+
+    volume1 = File(exists=True, desc="3D/4D volume", mandatory=True)
+    volume2 = File(exists=True, desc="3D/4D volume", mandatory=True)
+    mask1 = File(exists=True, desc="3D volume")
+    mask2 = File(exists=True, desc="3D volume")
+    metric = traits.Either(traits.Enum('cc', 'cr', 'crl1', 'mi', 'nmi', 'slr'),
+                          traits.Callable(),
+                         desc="""str or callable
+Cost-function for assessing image similarity. If a string,
+one of 'cc': correlation coefficient, 'cr': correlation
+ratio, 'crl1': L1-norm based correlation ratio, 'mi': mutual
+information, 'nmi': normalized mutual information, 'slr':
+supervised log-likelihood ratio. If a callable, it should
+take a two-dimensional array representing the image joint
+histogram as an input and return a float.""", usedefault=True)
+
+
+class SimilarityOutputSpec(TraitedSpec):
+    similarity = traits.List( traits.Float(desc="Similarity between volume 1 and 2, frame by frame"))
+
+
+class Similarity(BaseInterface):
+    """Calculates similarity between two 3D or 4D volumes. Both volumes have to be in
+    the same coordinate system, same space within that coordinate system and
+    with the same voxel dimensions.
+
+    .. note:: This interface is an extension of nipype.interfaces.nipy.utils.Similarity
+              to support 4D files.
+
+    Example
+    -------
+    >>> from nipype.interfaces.nipy.utils import Similarity
+    >>> similarity = Similarity()
+    >>> similarity.inputs.volume1 = 'rc1s1.nii'
+    >>> similarity.inputs.volume2 = 'rc1s2.nii'
+    >>> similarity.inputs.mask1 = 'mask.nii'
+    >>> similarity.inputs.mask2 = 'mask.nii'
+    >>> similarity.inputs.metric = 'cr'
+    >>> res = similarity.run() # doctest: +SKIP
+    """
+
+    input_spec = SimilarityInputSpec
+    output_spec = SimilarityOutputSpec
+
+    def _run_interface(self, runtime):
+
+        vol1_nii = nb.load(self.inputs.volume1)
+        vol2_nii = nb.load(self.inputs.volume2)
+
+        dims = vol1_nii.get_data().ndim
+
+        if dims==3 or dims==2:
+            vols1 = [ vol1_nii ]
+            vols2 = [ vol2_nii ]
+        if dims==4:
+            vols1 = nb.four_to_three( vol1_nii )
+            vols2 = nb.four_to_three( vol2_nii )
+
+        if dims<2 or dims>4:
+            raise RuntimeError( 'Image dimensions not supported (detected %dD file)' % dims )
+
+        if isdefined(self.inputs.mask1):
+            mask1 = nb.load(self.inputs.mask1).get_data() == 1
+        else:
+            mask1 = None
+
+        if isdefined(self.inputs.mask2):
+            mask2 = nb.load(self.inputs.mask2).get_data() == 1
+        else:
+            mask2 = None
+
+        self._similarity = []
+
+        for ts1,ts2 in zip( vols1, vols2 ):
+            histreg = HistogramRegistration(from_img = ts1,
+                                            to_img = ts2,
+                                            similarity=self.inputs.metric,
+                                            from_mask = mask1,
+                                            to_mask = mask2)
+            self._similarity.append( histreg.eval(Affine()) )
+
+        return runtime
+
+    def _list_outputs(self):
+        outputs = self._outputs().get()
+        outputs['similarity'] = self._similarity
+        return outputs

nipype/interfaces/nipy/utils.py

@@ -68,6 +68,12 @@ class Similarity(BaseInterface):
     input_spec = SimilarityInputSpec
     output_spec = SimilarityOutputSpec
 
+    def __init__(self, **inputs):
+        warnings.warn(("This interface is deprecated since 0.10.0."
+                      " Please use nipype.algorithms.metrics.Similarity"),
+                      DeprecationWarning)
+        super(BaseInterface,self).__init__(**inputs)
+
     def _run_interface(self, runtime):
 
         vol1_nii = nb.load(self.inputs.volume1)