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.

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 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 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 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 PyMedPhys [PyMedPhys] 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 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 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 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 3D volume or 2D slice.

  • ValueError – If the value of DD, DTA, DCO, globalNorm or stepSize is out of range, or DDType or mode cannot be recognised.

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

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. (def. 256)

Returns:

An instance of matplotlib.colors.LinearSegmentedColormap object.

Return type:

colormap

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))