getMetric: 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"), ...)

## 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"), ...)

## 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"), ...)

## 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"), ...)

Arguments

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

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

...

Further arguments. fixed=TRUE is passed to grep for exact matching of patID and structure. Arguments passed to getEUD

Value

A data frame or a list with details on the calculated metrics.
patIDPatient ID
structureStructure
metricThe calculated DVH metric
observedThe observed value for the DVH metric

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.

"DEUD": The generalized equivalent uniform dose (gEUD). SeegetEUDfor mandatory and optional parameters.
"DNTCP": The normal tissue complication probability (NTCP). SeegetNTCPfor mandatory and optional parameters.
"DTCP": The tumor control probability (TCP). SeegetNTCPfor 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:

1st letter"D"or"V":"D"If the requested value is a dose,"V"if it is a volume.
2nd element: 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: 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 or"cGy"for Centigray, relative doses by"%".
Optional 4th element_: 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.

References

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

Run this code

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

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

Run the code above in your browser using DataLab