R: Calculate dose-volume-histogram metrics

getMetric {DVHmetrics}

R Documentation

Calculate dose-volume-histogram metrics

Description

Simultaneously calculates multiple metrics for multiple cumulative DVHs.

Usage

getMetric(x, metric, patID, structure,
           sortBy=c("none", "observed", "patID", "structure", "metric"),
          splitBy=c("none", "patID", "structure", "metric"),
           interp=c("linear", "spline", "ksmooth"), fixed=TRUE, ...)

## S3 method for class 'DVHs'
getMetric(x, metric, patID, structure,
           sortBy=c("none", "observed", "patID", "structure", "metric"),
          splitBy=c("none", "patID", "structure", "metric"),
           interp=c("linear", "spline", "ksmooth"), fixed=TRUE, ...)

## S3 method for class 'DVHLst'
getMetric(x, metric, patID, structure,
           sortBy=c("none", "observed", "patID", "structure", "metric"),
          splitBy=c("none", "patID", "structure", "metric"),
           interp=c("linear", "spline", "ksmooth"), fixed=TRUE, ...)

## S3 method for class 'DVHLstLst'
getMetric(x, metric, patID, structure,
           sortBy=c("none", "observed", "patID", "structure", "metric"),
          splitBy=c("none", "patID", "structure", "metric"),
           interp=c("linear", "spline", "ksmooth"), fixed=TRUE, ...)

Arguments

`x`	One cumulative DVH (object of class `DVHs`, multiple cumulative DVHs from one patient with multiple structures (object of class `DVHLst`), or multiple cumulative DVHs from many patients, each with multiple structures (object of class `DVHLstLst`). See `readDVH`.
`metric`	`character` vector defining one or more DVH metrics. See Details for their definition. For metrics involving the relative dose, the DVH must contain the prescription dose.
`patID`	`character` vector. Calculate given DVH metrics for these patients only. If missing, DVH metrics are calculated for all patients. Can be a regular expression if additional argument `fixed=FALSE` is supplied as well, see `regex`.
`structure`	`character` vector. Calculate given DVH metrics for these structures only. If missing, DVH metrics are calculated for all structures. Can be a regular expression if additional argument `fixed=FALSE` is supplied as well, see `regex`.
`sortBy`	`character` vector giving the sorting criteria for the output data frame.
`splitBy`	`character` vector. Split results into a list of data frames where list components are defined by groups from combining these variables.
`interp`	`character`. Method of interpolation between DVH points: Linear interpolation using `approx`, monotone Hermite spline interpolation using `splinefun`, or local polynomial regression using `locpoly` with kernel bandwidth chosen by the direct plug-in method using `dpill`.
`fixed`	`logical`. Use `fixed=FALSE` for regular expression matching of `patID` and `structure`.
`...`	Further arguments passed to `getEUD` (for `metric="DEUD"`), `getTCP` (for `metric="DTCP"`), or `getNTCP` (for `metric="DNTCP"`).

Details

A pre-specified DVH metric is one of the following character strings:

"DMEAN": The volume-weighted mean dose of the structure.
"DMEDIAN": Median dose, equal to D50%
"DMIN": The minimum dose of the non-zero-dose voxels in the structure.
"DMAX": The maximum dose of the non-zero-dose voxels in the structure.
"DSD": The standard deviation of the dose in the structure.
"DRX": The prescription dose.
"DHI": The Homogeneity Index according to ICRU 83: (D2%-D98%)/D50%.
"DEUD": The generalized equivalent uniform dose (gEUD). See getEUD for mandatory and optional parameters.
"DNTCP": The normal tissue complication probability (NTCP). See getNTCP for mandatory and optional parameters.
"DTCP": The tumor control probability (TCP). See getNTCP for mandatory and optional parameters.

A free DVH metric is a character string which has three mandatory elements and one optional element in the following order (AAPM TG263 2018, section 9.2, note that complementary / cold metrics are not yet implemented):

1st letter "D" or "V": "D" If the requested value is a dose, "V" if it is a volume.
2nd element <number>: If the first letter is "D", this gives the volume for which the dose value of the cumulative DVH should be reported. If the first letter is "V", this gives the dose for which the volume value of the cumulative DVH should be reported.
3rd element <measurement unit>: The measurement unit for the 2nd element of the metric. Absolute volumes are indicated by "CC" for cubic centimeter, relative volumes by "%". Absolute doses are indicated by "Gy" for Gray, "cGy" for Centigray, or "eV/g" for uncalibrated dose in DVHs exported by PRIMO. Relative doses are indicated by "%".
Optional 4th element _<measurement unit>: The measurement unit of the output value. Possible units are as for the 3rd element. If missing, dose is reported as absolute dose in the measurement unit used in the DVH. Volume is reported as relative volume in %.

Examples:

"D1%": Minimal absolute dose for the "hottest" 1% of the structure, i.e., the maximally irradiated 1% of the structure was exposed to at least this absolute dose.
"D1CC_%": Minimal relative dose (% of prescription dose) for the maximally irradiated cm^3 of the structure.
"V500cGy": Relative structure volume in % that was exposed to at least 500cGy.
"V10%_CC": Absolute structure volume in cm^3 that was exposed to at least 10% of prescription dose.

If volume or dose values outside the range of possible values for a structure are requested, metrics cannot be calculated, and the result will be NA with a warning.

DMEAN, DMEDIAN, DMIN, DMAX, DSD are taken from the exported DVH if present. Otherwise, the differential DVH is generated and used for calculating these metrics.

Value

A data frame or a list with details on the calculated metrics.

`patID`	Patient ID
`structure`	Structure
`metric`	The calculated DVH metric
`observed`	The observed value for the DVH metric

References

American Association of Physicists in Medicine (AAPM) Task Group TG263 (2018). Standardizing Nomenclatures in Radiation Oncology. https://www.aapm.org/pubs/reports/RPT_263.pdf (section 9.2 "Guidelines for DVH metrics")

Rancati et al. (2004). Fitting late rectal bleeding data using different NTCP models: results from an Italian multi-centric study (AIROPROS0101). Radiotherapy Oncology, 73, 21-32.

Wu et al. (2002). Optimization of intensity modulated radiotherapy plans based on the equivalent uniform dose. International Journal of Radiation Oncology Biology Physics, 52, 224-235.

Examples

getMetric(dataMZ, c("D1CC", "V10%_CC"),
          sortBy=c("metric", "structure", "observed"))

# matching patients are P123 and P234
# matching structures are AMYOCL and AMYOCR
getMetric(dataMZ, c("D1CC", "V10%_CC"),
          patID="23",
          structure=c("AMYOC", "VALVE"),
          splitBy="patID",
          fixed=FALSE)

# gEUD with a=2
getMetric(dataMZ[[c(1, 1)]], "DEUD", EUDa=2)

# gEUD based on EQD2 with a=2, 20 fractions
getMetric(dataMZ[[c(1, 1)]], "DEUD", EUDa=2, EUDfd=1.8)

# NTCP Lyman probit model with TD50=20, m=4, n=0.5
getMetric(dataMZ[[c(1, 1)]], "DNTCP",
          NTCPtd50=20, NTCPm=4, NTCPn=0.5, NTCPtype="probit")

[Package DVHmetrics version 0.4.2 Index]