nipype.algorithms.metrics module

Image assessment algorithms. Typical overlap and error computation measures to evaluate results from other processing units.

Distance

Link to code

Bases: BaseInterface

Calculates distance between two volumes.

Mandatory Inputs:
  • volume1 (a pathlike object or string representing an existing file) – Has to have the same dimensions as volume2.

  • volume2 (a pathlike object or string representing an existing file) – Has to have the same dimensions as volume1.

Optional Inputs:
  • mask_volume (a pathlike object or string representing an existing file) – Calculate overlap only within this mask.

  • method (‘eucl_min’ or ‘eucl_cog’ or ‘eucl_mean’ or ‘eucl_wmean’ or ‘eucl_max’) – “”eucl_min”: Euclidean distance between two closest points “eucl_cog”: mean Euclidean distance between the Center of Gravity of volume1 and CoGs of volume2 “eucl_mean”: mean Euclidean minimum distance of all volume2 voxels to volume1 “eucl_wmean”: mean Euclidean minimum distance of all volume2 voxels to volume1 weighted by their values “eucl_max”: maximum over minimum Euclidean distances of all volume2 voxels to volume1 (also known as the Hausdorff distance). (Nipype default value: eucl_min)

Outputs:
  • distance (a float)

  • histogram (a pathlike object or string representing a file)

  • point1 (an array with shape (3,))

  • point2 (an array with shape (3,))

ErrorMap

Link to code

Bases: BaseInterface

Calculates the error (distance) map between two input volumes.

Example

>>> errormap = ErrorMap()
>>> errormap.inputs.in_ref = 'cont1.nii'
>>> errormap.inputs.in_tst = 'cont2.nii'
>>> res = errormap.run() 
Mandatory Inputs:
  • in_ref (a pathlike object or string representing an existing file) – Reference image. Requires the same dimensions as in_tst.

  • in_tst (a pathlike object or string representing an existing file) – Test image. Requires the same dimensions as in_ref.

  • metric (‘sqeuclidean’ or ‘euclidean’) – Error map metric (as implemented in scipy cdist). (Nipype default value: sqeuclidean)

Optional Inputs:
  • mask (a pathlike object or string representing an existing file) – Calculate overlap only within this mask.

  • out_map (a pathlike object or string representing a file) – Name for the output file.

Outputs:
  • distance (a float) – Average distance between volume 1 and 2.

  • out_map (a pathlike object or string representing an existing file) – Resulting error map.

FuzzyOverlap

Link to code

Bases: SimpleInterface

Calculates various overlap measures between two maps, using the fuzzy definition proposed in: Crum et al., Generalized Overlap Measures for Evaluation and Validation in Medical Image Analysis, IEEE Trans. Med. Ima. 25(11),pp 1451-1461, Nov. 2006.

in_ref and in_tst are lists of 2/3D images, each element on the list containing one volume fraction map of a class in a fuzzy partition of the domain.

Example

>>> overlap = FuzzyOverlap()
>>> overlap.inputs.in_ref = [ 'ref_class0.nii', 'ref_class1.nii' ]
>>> overlap.inputs.in_tst = [ 'tst_class0.nii', 'tst_class1.nii' ]
>>> overlap.inputs.weighting = 'volume'
>>> res = overlap.run() 
Mandatory Inputs:
  • in_ref (a list of items which are a pathlike object or string representing an existing file) – Reference image. Requires the same dimensions as in_tst.

  • in_tst (a list of items which are a pathlike object or string representing an existing file) – Test image. Requires the same dimensions as in_ref.

Optional Inputs:
  • in_mask (a pathlike object or string representing an existing file) – Calculate overlap only within mask.

  • out_file (a pathlike object or string representing a file) – Alternative name for resulting difference-map. (Nipype default value: diff.nii)

  • weighting (‘none’ or ‘volume’ or ‘squared_vol’) – ‘none’: no class-overlap weighting is performed. ‘volume’: computed class-overlaps are weighted by class volume ‘squared_vol’: computed class-overlaps are weighted by the squared volume of the class. (Nipype default value: none)

Outputs:
  • class_fdi (a list of items which are a float) – Array containing the fDIs of each computed class.

  • class_fji (a list of items which are a float) – Array containing the fJIs of each computed class.

  • dice (a float) – Fuzzy Dice Index (fDI), all the classes.

  • jaccard (a float) – Fuzzy Jaccard Index (fJI), all the classes.

Overlap

Link to code

Bases: BaseInterface

Calculates Dice and Jaccard’s overlap measures between two ROI maps. The interface is backwards compatible with the former version in which only binary files were accepted.

The averaged values of overlap indices can be weighted. Volumes now can be reported in \(mm^3\), although they are given in voxels to keep backwards compatibility.

Example

>>> overlap = Overlap()
>>> overlap.inputs.volume1 = 'cont1.nii'
>>> overlap.inputs.volume2 = 'cont2.nii'
>>> res = overlap.run() 
Mandatory Inputs:
  • bg_overlap (a boolean) – Consider zeros as a label. (Nipype default value: False)

  • vol_units (‘voxel’ or ‘mm’) – Units for volumes. (Nipype default value: voxel)

  • volume1 (a pathlike object or string representing an existing file) – Has to have the same dimensions as volume2.

  • volume2 (a pathlike object or string representing an existing file) – Has to have the same dimensions as volume1.

Optional Inputs:
  • mask_volume (a pathlike object or string representing an existing file) – Calculate overlap only within this mask.

  • out_file (a pathlike object or string representing a file) – (Nipype default value: diff.nii)

  • weighting (‘none’ or ‘volume’ or ‘squared_vol’) – ‘none’: no class-overlap weighting is performed. ‘volume’: computed class-overlaps are weighted by class volume ‘squared_vol’: computed class-overlaps are weighted by the squared volume of the class. (Nipype default value: none)

Outputs:
  • dice (a float) – Averaged dice index.

  • diff_file (a pathlike object or string representing an existing file) – Error map of differences.

  • jaccard (a float) – Averaged jaccard index.

  • labels (a list of items which are an integer) – Detected labels.

  • roi_di (a list of items which are a float) – The Dice index (DI) per ROI.

  • roi_ji (a list of items which are a float) – The Jaccard index (JI) per ROI.

  • roi_voldiff (a list of items which are a float) – Volume differences of ROIs.

  • volume_difference (a float) – Averaged volume difference.

Similarity

Link to code

Bases: NipyBaseInterface

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. Requires nipy

Example

>>> from nipype.algorithms.metrics 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() 
Mandatory Inputs:
  • volume1 (a pathlike object or string representing an existing file) – 3D/4D volume.

  • volume2 (a pathlike object or string representing an existing file) – 3D/4D volume.

Optional Inputs:
  • mask1 (a pathlike object or string representing an existing file) – 3D volume.

  • mask2 (a pathlike object or string representing an existing file) – 3D volume.

  • metric (‘cc’ or ‘cr’ or ‘crl1’ or ‘mi’ or ‘nmi’ or ‘slr’ or a callable value) – 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. (Nipype default value: None)

Outputs:

similarity (a list of items which are a float)