Gamma Index Analyse

A collection of functions for the Gamma Index analysis.

Warning

The GI analysis is performed in an external C++ used as a shared library and is still in the development and validation.

fredtools.calcGammaIndex(imgRef, imgEval, DD, DTA, DCO, DDType='local', globalNorm=None, stepSize=10, fractionalStepSize=True, mode='gamma', CPUNo='auto', displayInfo=False)

Calculate gamma index map.

The function calculates the gamma index map using the imgRef and imgEval, defined SimpleITK image objects, as the reference and evaluation images, respectively. The gamma index test is performed with a defined dose distance (DD) given in [%], distance to agreement (DTA) given in the same length unit as the reference image (in [mm] by default) and is calculated for the dose values greater or equal than a fraction of the maximum dose in the reference image, given by the DCO parameter. The gamma index can be calculated for local or global dose difference in two modes:

  • gamma: each voxel represents the gamma index value and the voxels excluded from the GI analysis have values -1.

  • pass-rate: each voxel represents passing (1) or falling (0) of the gamma index test and the voxels excluded from the GI analysis have values -1.

The gamma index calculation is performed by an external C++ library complied as a Linux shared library. The gamma index engine was developed by Angelo Schiavi and validated against PyMedPhys [1] python library.

Parameters:

  • imgRef (SimpleITK Image) – An object of a SimpleITK 2D or 3D image describing the reference.

  • imgEval (SimpleITK Image) – An object of a SimpleITK 2D or 3D image describing the evaluation.

  • DD (float) – Dose distance in [%].

  • DTA (float) – Distance-to-agreement, usually in [mm].

  • DCO (float) – Lower dose cutoff below which gamma will not be calculated given as the fraction of the maximum reference value.

  • DDType ({'local', 'global'}, optional) –

    Method of calculating the absolute dose difference criterion. (def. ‘local’):

    • ’local’ : the absolute dose difference calculated as DD percent of the local reference value.

    • ’global’ : the absolute dose difference calculated as DD percent of the maximum reference value.

  • globalNorm (float, optional) – Global normalisation of the input images. If not given or None then the maximum value of the reference image is used. (def. None)

  • stepSize (float, optional) – Step size to search for minimum gamma index value. Can be given as an absolute value in the reference length unit (for instance in [mm]) or as the fraction of the distance-to-agreement if fractionalStepSize=True. (def. 10)

  • fractionalStepSize (bool, optional) – Determine if the stepSize should be treated as the absolute value (false) or the fraction of the distance-to-agreement (true). (def. True).

  • mode ({'gamma', 'pass-rate'}, optional) –

    Mode of calculation. (def. ‘gamma’):

    • ’gamma’: each voxel represents the gamma index value and the voxels excluded from the GI analysis have values -1.

    • ’pass-rate’: each voxel represents passing (1) or falling (0) of the gamma index test and the voxels excluded from the GI analysis have values -1.

  • CPUNo ({'auto', 'none'}, scalar or None, optional) – Define if the multiprocessing should be used and how many cores should be exploited. Can be None, then no multiprocessing will be used, a string ‘auto’, then the number of cores will be determined by os.cpu_count(), or a scalar defining the number of CPU cores to be used. (def. ‘auto’)

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

An object of a SimpleITK image describing the gamma index. It is of float or integer type when the calculation mode is ‘gamma’ or ‘pass-rate’, respectively.

Return type:

SimpleITK Image

Raises:

RuntimeError –

Run time error is raised when the execution of the gamma calculation failed. The following error codes can be raised:

  • -1 : generic error

  • -20 : value range error

  • -21 : value is nan error

  • -22 : value is inf error

  • -29 : null pointer error

  • -50 : illdefined vector

  • -51 : illdefined dimensions

  • -52 : illdefined spacing

  • -53 : illdefined offset

  • -100 : computation ongoing

  • -101 : setup not complete

  • -102 : criteria not defined

  • -103 : ref map not defined

  • -104 : eval map not defined

  • -105 : computation not done

See also

getGIstat

calculate the gamma index statistics including the gamma index pass rate.

Examples

See example jupyter notebook at [2]

References

fredtools.getGIstat(imgGI, displayInfo=False)

Get statistics of Gamma Index.

The function calculates Gamma Index statistics from an image defined as a SimpleITK image object. Two modes of the gamma index calculation are recognized automatically based on the image type:

  • gamma (float): each voxel represents the gamma index value and the voxels excluded from the GI analysis have values -1 or numpy.nan.

  • pass-rate (integer): each voxel represents passing (1) or falling (0) of the gamma index test and the voxels excluded from the GI analysis have values -1.

Parameters:

  • imgGI (SimpleITK Image) – An object of a SimpleITK image.

  • displayInfo (bool, optional) – Displays a summary of the function results. (def. False)

Returns:

Dictionary with the gamma index statistics.

Return type:

dict

See also

calcGammaIndex

calculate the Gamma Index map for two images.