Gamma Index Analysis

A collection of functions for the Gamma Index (GI) analysis, implemented in the fredtools.GammaIndex subpackage.

Note

The GI calculation is performed by an external C++ library compiled as a shared library, which is distributed with FREDtools. Currently, only the Linux version of the shared library is available.

The gamma index engine has been validated against the independent implementations in PyMedPhys and plastimatch. The comparison, together with a description of the algorithms and the reasons why the results of the tools are never exactly the same, is presented in the Gamma Index Validation Report.

fredtools.calcGammaIndex(imgRef: Image, imgEval: Image, DD: Annotated[int | float | number, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=0), Le(le=100)])], DTA: int | float | number, DCO: Annotated[int | float | number, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Ge(ge=0), Le(le=1)])], DDType: Literal['local', 'global'] = 'local', globalNorm: int | float | number | None = None, stepSize: int | float | number = 10, fractionalStepSize: bool = True, mode: Literal['gamma', 'pass-rate'] = 'gamma', displayInfo: bool = False) → Image

Calculate gamma index map.

The function calculates the gamma index map using the imgRef and imgEval, defined SimpleITK 3D image objects, as the reference and evaluation images, respectively. The gamma index test is performed with a defined dose difference (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 global normalisation dose (the maximum dose in the reference image by default), 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 failing (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 compiled as a Linux shared library. The gamma index engine was developed by Angelo Schiavi and validated against the PyMedPhys [PyMedPhys] python library and the plastimatch [Plastimatch] gamma index tool (see the Gamma Index Validation Report).

Parameters:

  • imgRef (SimpleITK Image) – An object of a SimpleITK 3D image describing the reference. The image must have a scalar pixel type and at least two voxels along each axis.

  • imgEval (SimpleITK Image) – An object of a SimpleITK 3D image describing the evaluation, with the same requirements as for the imgRef. It can have a different size, spacing and origin than the imgRef but must have the same direction matrix.

  • DD (float) – Dose difference 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 global normalisation dose (the maximum reference value by default, see globalNorm).

  • 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 dose in the units of the input images, used to calculate the dose cutoff (DCO) and the ‘global’ dose difference criterion (DD). 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 the minimum gamma index value. It can be given as an absolute step in the reference length unit (for instance in [mm]) if fractionalStepSize is False, or as the number of subdivisions of the distance-to-agreement if fractionalStepSize is True, so that the search step is calculated as DTA/stepSize. (def. 10)

  • fractionalStepSize (bool, optional) – Determine if the stepSize should be treated as the absolute step value (False) or as the number of subdivisions of the distance-to-agreement (True), meaning that the search step is DTA/stepSize. (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 failing (0) of the gamma index test and the voxels excluded from the GI analysis have values -1.

  • 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:

  • TypeError – If imgRef or imgEval is not an instance of a SimpleITK image object describing a scalar 3D volume (e.g. a vector image).

  • NotImplementedError – If imgRef or imgEval is a 2D image or has an axis of size 1. Such images are not supported by the current version of the gamma index library.

  • ValueError – If the value of DD, DTA, DCO, globalNorm or stepSize is out of range, DDType or mode cannot be recognised, the direction matrices of imgRef and imgEval do not match, any of the images contains NaN or Inf values, the maximum of the reference image is not positive, or no voxel of the reference image is above the dose cutoff.

  • OSError – If the function is run on a platform other than Linux (only the Linux shared library is implemented).

  • RuntimeError –

    Run time error is raised when the execution of the gamma calculation failed or the library returned an invalid result (no voxel analysed). 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 : ill-defined vector

    • -51 : ill-defined dimensions

    • -52 : ill-defined spacing

    • -53 : ill-defined 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.

Notes

The gamma index pass rates calculated with this function agree within 1 percentage point with PyMedPhys and plastimatch. Identical gamma index maps are not expected, because the tools discretise the search space and interpolate the evaluation dose differently. Refer to the Gamma Index Validation Report to read more about the validation results.

The images are required to be 3D and to have the same direction matrix. The calculation is performed in the common index frame of the images, which preserves the distances for any common direction matrix, and the resulting gamma index map is returned in the frame of reference of the imgRef. The dose cutoff in dose units is DCO times the global normalisation dose and the ‘global’ dose difference criterion is DD percent of the global normalisation dose, which is the maximum of the reference image unless globalNorm is given.

Examples

See example jupyter notebook at [GITutorial]

References

fredtools.getGIstat(imgGI: Image, displayInfo: bool = False) → DottedDict

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 recognised 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 failing (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:

A dictionary-like object (DottedDict) with the gamma index statistics with the keys: ‘passRate’ (gamma index pass rate in [%]), ‘mean’, ‘std’, ‘min’ and ‘max’ of the gamma index values. In the ‘pass-rate’ mode the ‘mean’, ‘std’, ‘min’ and ‘max’ values are numpy.nan.

Return type:

DottedDict

Raises:

  • TypeError – If imgGI is not an instance of a SimpleITK image object, or the image is neither of integer nor float type.

  • ValueError – If the image is of integer type (‘pass-rate’ mode) but contains unique values other than -1, 0 and 1.

See also

calcGammaIndex

calculate the Gamma Index map for two images.

fredtools.getGIcmap(maxGI: int | float | number, N: Annotated[int, Ge(ge=0)] = 256) → LinearSegmentedColormap

Get colormap for Gamma Index images.

The function creates a colormap for Gamma Index (GI) images, that can be used by matplotlib.pyplot.imshow function for displaying 2D images. The colormap is created from 0 to the maxGI value, whereas from 0 to 1 (GI test passed) the color changes from dark blue to white, and from 1 to maxGI it changes from light red to red.

Parameters:

  • maxGI (scalar) – The maximum value of the colormap. Values less than 1 are clamped to 1 (with a warning).

  • N (int, optional) – Number of segments of the colormap, at least 2. (def. 256)

Returns:

An instance of matplotlib.colors.LinearSegmentedColormap object.

Return type:

colormap

Raises:

ValueError – If N is not an integer greater than 1.

See also

calcGammaIndex

calculate the Gamma Index for two images.

Examples

It is assumed that the img is an image describing a slice of Gamma Index (GI) values calculated up to maximum value 3. To plot the GI map with the GI colormap:

>>> plt.imshow(ft.arr(img), cmap=getGIcmap(maxGI=3))