Gamma

API

pymedphys.gamma(axes_reference, dose_reference, axes_evaluation, dose_evaluation, dose_percent_threshold, distance_mm_threshold, lower_percent_dose_cutoff=20, interp_fraction=10, max_gamma=None, local_gamma=False, global_normalisation=None, skip_once_passed=False, random_subset=None, ram_available=1610612736, quiet=None, interp_algo='pymedphys', random_state=None, exclude_nan_reference=False)

Compare two dose grids with the gamma index.

It computes 1, 2, or 3 dimensional gamma with arbitrary grid sizes while interpolating on the fly. This function makes use of some of the ideas presented within <http://dx.doi.org/10.1118/1.2721657>.

Parameters:

• axes_reference (tuple) – The reference coordinates, in the same order as the dose dimensions. Ascending or descending axes retain their supplied order in the output.

• dose_reference (np.array) – The reference dose grid. Each point in the reference grid becomes the centre of a Gamma ellipsoid. For each point of the reference, nearby evaluation points are searched at increasing distances.

• axes_evaluation (tuple) – The evaluation coordinates. Axes may be ascending or descending. Descending axes and their dose values are reversed together internally; this does not change the reference grid or the output order. Uneven spacing uses the SciPy interpolator with a warning. An axis with a single value makes the evaluation grid a plane, line or point with no thickness, such as a single-frame RT Dose. Gamma then searches within that plane, line or point only, and adds each reference point’s perpendicular distance from it, so results do not depend on the coordinate origin.

• dose_evaluation (np.array) – The evaluation dose grid. Evaluation here is defined as the grid which is interpolated and searched over at increasing distances away from each reference point.

• dose_percent_threshold (float) – The percent dose threshold

• distance_mm_threshold (float) – The gamma distance threshold. Units must match of the coordinates given.

• lower_percent_dose_cutoff (float, optional) – The percent lower dose cutoff below which gamma will not be calculated. This is only applied to the reference grid.

• interp_fraction (float, optional) – The fraction which gamma distance threshold is divided into for interpolation. Defaults to 10 as recommended within <http://dx.doi.org/10.1118/1.2721657>. If a 3 mm distance threshold is chosen this default value would mean that the evaluation grid is interpolated at a step size of 0.3 mm.

• max_gamma (float, optional) – The largest gamma value reported. This can be used to speed up calculation: once a search distance is reached that would give gamma values larger than this parameter, the search stops, and larger values are reported as max_gamma. It must be greater than 1, so that it never changes whether a point passes (gamma <= 1). Defaults to np.inf. The search also stops when shells can no longer reach the evaluation grid.

• local_gamma – Designates local gamma should be used instead of global. Defaults to False. Local gamma is undefined where the reference dose is zero, so a ValueError is raised if any analysed reference point is zero.

• global_normalisation (float, optional) – The dose normalisation value that the percent inputs calculate from. Defaults to the maximum value of dose_reference. It must be finite and positive.

• random_subset (int, optional) – Number of reference points to sample from those at or above the lower dose cutoff. This is a count, not a fraction. If it exceeds the number of eligible points, all eligible points are used.

• ram_available (int, optional) – RAM budget in bytes used to split interpolation work into chunks. Defaults to 1.5 GiB (1610612736 bytes), also used when None is passed. This is not a limit on total process memory.

• quiet (bool, optional) – Deprecated but maintained for now for backwards compatibility. pymedphys.gamma now utilises the logging module. You can set your desired verbosity by setting the corresponding logging level. Basic information is given for the info level. Additional information using for benchmarking or troubleshooting performance is provided for the debug level.

• interp_algo ({"pymedphys", "scipy"}, optional) – Interpolation implementation. Defaults to “pymedphys”. The “scipy” option uses scipy.interpolate.RegularGridInterpolator.

• random_state (int or numpy.random.Generator, optional) – Seed or generator that selects the random_subset, so the subset can be reproduced. Defaults to None, which uses NumPy’s global random state as before, so numpy.random.seed() still applies.

• exclude_nan_reference (bool, optional) – Leave reference points whose dose is NaN out of the analysis, for example unmeasured detector positions or points outside a region of interest. They are reported as NaN, and the default global_normalisation ignores them. Defaults to False, which raises ValueError if dose_reference contains NaN, so that NaN from an upstream error is not silently dropped. Infinite reference doses, and NaN or infinite evaluation doses, always raise.

Returns:

Each returned gamma array has the same shape and index order as dose_reference. Its values belong to axes_reference; use those coordinates when plotting. If the reference was obtained from pymedphys.dicom.zyx_and_dose_from_dataset(), its order can differ from the DICOM dataset’s raw pixel_array.

A reference point is analysed when its dose is at or above the lower dose cutoff (so NaN, excluded with exclude_nan_reference, is not) and, if random_subset is set, it was selected. Every analysed reference point has a value; NaN marks only the reference points that were not analysed. pymedphys.gamma_pass_rate() gives the percentage of analysed reference points that pass.

An analysed reference point outside the evaluation grid is compared with the evaluation data up to the grid’s edge, so it may fail. A warning gives the number of such points more than one search step (the smallest distance threshold divided by interp_fraction) outside the grid. Crop the reference grid to the region the evaluation grid covers if only that region should be analysed.

Return type:

gamma

Raises:

ValueError – If either dose grid contains infinite values, dose_evaluation contains NaN, dose_reference contains NaN (unless exclude_nan_reference=True) or no finite values, max_gamma is not greater than 1, global_normalisation is not finite and positive, or local gamma is requested and an analysed reference point has zero dose.

pymedphys.gamma_pass_rate(gamma) → float

The percentage of analysed reference points that pass gamma.

A point passes when its gamma is at most 1. NaN marks reference points that pymedphys.gamma() did not analyse (below the lower dose cutoff, not selected by random_subset, or with NaN dose left out by exclude_nan_reference), so they are left out of both the count and the total, as are the masked values of a masked array.

Every NaN is taken to mark a point that was not analysed. Gamma from other software, or from pymedphys.gamma() before version 0.42.0, can also be NaN at analysed points, which would then be left out and raise the pass rate. Recalculate such gamma with this version of pymedphys.gamma() first.

Parameters:

gamma (array_like) – Gamma values of any shape, as returned by pymedphys.gamma() for one pair of dose and distance thresholds.

Returns:

The pass rate, in percent.

Return type:

float

Raises:

• TypeError – If gamma is the dict that pymedphys.gamma() returns for several thresholds, rather than one of its values.

• ValueError – If no reference point was analysed, so every value is NaN or masked, or if any gamma value is negative.