Analyze Dose-Volume Histograms and Check Constraints

Description

Functionality for analyzing dose-volume histograms (DVH) in radiation oncology: Read DVH text files, calculate DVH metrics, gEUD, BED, EQD2, NTCP, TCP, show DVH diagrams, check and visualize quality assurance constraints for the DVH. Includes web-based graphical user interface.

Details

Author(s)

Daniel Wollschlaeger and Heiko Karle

Maintainer: Daniel Wollschlaeger <wollschlaeger@uni-mainz.de>

References

For a solution that also reads files in DICOM-RT format, see the RadOnc package: https://CRAN.R-project.org/package=RadOnc.

Examples

showDVH(dataMZ[[1]])
checkConstraint(dataMZ, "D1CC < 10Gy")

Check constraints on dose-volume histograms (DVH)

Description

Simultaneously checks one or more quality assurance constraints on one or more DVHs. Reports compliance with each constraint as well as observed difference between linearly interpolated DVH and the given constraints in terms of (relative) dose, (relative) volume, and (relative) minimal Euclidean distance.

Usage

checkConstraint(x, constr, byPat=TRUE, semSign=FALSE,
                sortBy=c("none", "observed", "compliance", "structure",
                         "constraint", "patID", "deltaV", "deltaD",
                         "dstMin", "dstMinRel"),
                interp=c("linear", "spline", "smooth"), ...)

## S3 method for class 'DVHs'
checkConstraint(x, constr, byPat=TRUE, semSign=FALSE,
                sortBy=c("none", "observed", "compliance", "structure",
                         "constraint", "patID", "deltaV", "deltaD",
                         "dstMin", "dstMinRel"),
                interp=c("linear", "spline", "smooth"), ...)

## S3 method for class 'DVHLst'
checkConstraint(x, constr, byPat=TRUE, semSign=FALSE,
                sortBy=c("none", "observed", "compliance", "structure",
                         "constraint", "patID", "deltaV", "deltaD",
                         "dstMin", "dstMinRel"),
                interp=c("linear", "spline", "smooth"), ...)

## S3 method for class 'DVHLstLst'
checkConstraint(x, constr, byPat=TRUE, semSign=FALSE,
                sortBy=c("none", "observed", "compliance", "structure",
                         "constraint", "patID", "deltaV", "deltaD",
                         "dstMin", "dstMinRel"),
                interp=c("linear", "spline", "smooth"), ...)

Arguments

Details

A DVH constraint is a character string that consists of three parts: The DVH metric, the comparison operator (<, >, <=, >=), and the reference value together with the measurement unit. See getMetric for defining a DVH metric, as well as for possible measurement units for dose and volume. For constraints involving the relative dose, the DVH must contain the prescription dose.

Some example constraints are "V10Gy > 80%" (more than 80% of the structure should have received 10Gy), "V20% < 10CC" (less than 10cm^3 of the structure should have received 20% of the prescription dose), or "D10CC > 500cGy" (The "hottest" 10cm^3 of the structure should have received more than 500cGy).

For constraints on DEUD, DNTCP and DTCP (see getMetric), the reference measurement unit must be Gy, cGy, even though NTCP and TCP are probabilities. Example: "DNTCP < 0.5Gy".

A DVH constraint can apply to a specific patient or to all patients, and to a specific structure or to all structures.

• If constraints apply to all patients/structures in x, constr can be a character vector with elements like the examples above.

• If constraints apply only to some patients/structures, constr must be a data frame with variables constraint, patID and structure. Each row then defines one constraint and its scope: constraint must be a character string with one constraint definition as in the examples above. patID must be either a character string with a valid patient ID or "*" if the the constraint applies to all patients. structure must be either a character string with a valid structure or "*" if the the constraint applies to all structures. If variable patID is missing from the data frame, the constraints apply to all available patients. If variable structure is missing from the data frame, the constraints apply to all available structures. See readConstraint for reading appropriate constraint data.frames from external text files.

For calculating the minimal Euclidean distance between the constraint point and the DVH, the constraint point is orthogonally projected onto each DVH segment between (interpolated) DVH nodes. The relative Euclidean distance is the minimum of these distances divided by the distance of the constraint point to the closer one of both axes (dose and volume).

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.

Value

A data frame with details on constraint compliance / violation.

See Also

getMetric, getEUD, getNTCP, getTCP, readConstraint, saveConstraint, showConstraint

Examples

res <- checkConstraint(dataMZ, c("D10CC < 10Gy", "V20Gy < 20%"))
head(res)

# define constraints
constr <- data.frame(
    patID=c("P123", "P234"),
    structure=c("HEART", "*"),
    constraint=c("D1CC < 20Gy", "V10% > 8CC"),
    stringsAsFactors=FALSE)       # this is important
checkConstraint(dataMZ, constr=constr)

Convert between differential and cumulative DVH

Description

Convert between differential and cumulative DVH as well as between dose units.

Usage

convertDVH(x, toType=c("asis", "cumulative", "differential"),
           toDoseUnit=c("asis", "GY", "CGY"),
           interp=c("asis", "linear"),
           nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'matrix'
convertDVH(x, toType=c("asis", "cumulative", "differential"),
           toDoseUnit=c("asis", "GY", "CGY"),
           interp=c("asis", "linear"),
           nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'DVHs'
convertDVH(x, toType=c("asis", "cumulative", "differential"),
           toDoseUnit=c("asis", "GY", "CGY"),
           interp=c("asis", "linear"),
           nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'DVHLst'
convertDVH(x, toType=c("asis", "cumulative", "differential"),
           toDoseUnit=c("asis", "GY", "CGY"),
           interp=c("asis", "linear"),
           nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'DVHLstLst'
convertDVH(x, toType=c("asis", "cumulative", "differential"),
           toDoseUnit=c("asis", "GY", "CGY"),
           interp=c("asis", "linear"),
           nodes=NULL, rangeD=NULL, perDose=TRUE)

Arguments

Value

Depending on the input, an object of class matrix, DVHs, DVHLst, or DVHLstLst.

See Also

convertDVHsmooth, readDVH, showDVH

Examples

res <- convertDVH(dataMZ[[c(1, 1)]],
                  toType="cumulative",
                  toDoseUnit="CGY")

Convert between differential and cumulative DVH

Description

Convert between differential and cumulative DVH as well as between dose units, using smoothng of the differential DVH.

Usage

convertDVHsmooth(x,
                 toType=c("asis", "cumulative", "differential"),
                 toDoseUnit=c("asis", "GY", "CGY"),
                 interp=c("asis", "linear", "spline", "ksmooth", "smoothSpl"),
                 nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'matrix'
convertDVHsmooth(x,
                 toType=c("asis", "cumulative", "differential"),
                 toDoseUnit=c("asis", "GY", "CGY"),
                 interp=c("asis", "linear", "spline", "ksmooth", "smoothSpl"),
                 nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'DVHs'
convertDVHsmooth(x,
                 toType=c("asis", "cumulative", "differential"),
                 toDoseUnit=c("asis", "GY", "CGY"),
                 interp=c("asis", "linear", "spline", "ksmooth", "smoothSpl"),
                 nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'DVHLst'
convertDVHsmooth(x,
                 toType=c("asis", "cumulative", "differential"),
                 toDoseUnit=c("asis", "GY", "CGY"),
                 interp=c("asis", "linear", "spline", "ksmooth", "smoothSpl"),
                 nodes=NULL, rangeD=NULL, perDose=TRUE)

## S3 method for class 'DVHLstLst'
convertDVHsmooth(x,
                 toType=c("asis", "cumulative", "differential"),
                 toDoseUnit=c("asis", "GY", "CGY"),
                 interp=c("asis", "linear", "spline", "ksmooth", "smoothSpl"),
                 nodes=NULL, rangeD=NULL, perDose=TRUE)

Arguments

Value

Depending on the input, an object of class matrix, DVHs, DVHLst, or DVHLstLst.

See Also

convertDVH, readDVH, showDVH

Examples

res <- convertDVHsmooth(dataMZ[[c(1, 1)]],
                  toType="cumulative",
                  toDoseUnit="CGY")

Constraint data frame

Description

Data frame with quality assurance constraints to use with built-in DVH object dataMZ.

Usage

data(dataConstr)

Format

A data frame with 6 entries for the following 3 variables.

constraint

The constraint character string.

patID

The patient ID character string or * wildcard.

structure

The structure character string or * wildcard.

Details

See checkConstraint for the definition of a constraint.

See Also

readConstraint, checkConstraint, showConstraint

Examples

checkConstraint(dataMZ, constr=dataConstr)

DVH data from 3 patients

Description

Data from 3 patients with radiotherapy. DVHs for 7 heart structures.

Usage

data(dataMZ)

Format

Object of class DVHLstLst with 3 components corresponding to 3 patients.

P123

Object of class DVHLst. 7 objects of class DVHs for structures AMYOCL (left anterior heart wall), AMYOCR (right anterior heart wall), AOVALVE (aortic valve), AVNODE (AV node), HEART (complete heart), PULMVALVE (pulmonary valve), MYOCARD (heart wall)

P234

Object of class DVHLst. 7 objects of class DVHs for the same structures as patient P123.

P345

Object of class DVHLst. 7 objects of class DVHs for the same structures as patient P123.

Details

Data courtesy of Department of Radiation Oncology (Prof. Dr. Schmidberger), University Medical Center Mainz, Germany.

See readDVH for classes DVHLstLst, DVHLst, and DVHs.

See Also

readDVH, print.DVHs

Examples

print(dataMZ, verbose=TRUE)

Calculate biologically effective dose (BED)

Description

Calculate biologically effective dose (BED) according to the linear-quadratic model.

Usage

getBED(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## Default S3 method:
getBED(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## S3 method for class 'DVHs'
getBED(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## S3 method for class 'DVHLst'
getBED(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## S3 method for class 'DVHLstLst'
getBED(D=NULL, fd=NULL, fn=NULL, ab=NULL)

Arguments

Value

Default method: A data frame with variables BED, fractDose, ab.

If D is some kind of DVH object, the same kind of object is returned with the individual dose values converted to BED.

References

Fowler, J. F. (2010). 21 years of Biologically Effective Dose. British Journal of Radiology, 83, 554-568.

See Also

getEQD2, getIsoEffD

Examples

getBED(D=50, fd=2.5, ab=c(2, 3, 4))
getBED(D=dataMZ[[c(1, 1)]], fd=1.8, ab=3)

DMEAN and other dose metrics

Description

Calculate DMEAN and other dose metrics from the (interpolated) differential DVH without relying on the values exported by the TPS.

Usage

getDMEAN(x, interp=c("linear", "spline", "ksmooth", "smoothSpl"),
         nodes=5001L)

## S3 method for class 'DVHs'
getDMEAN(x, interp=c("linear", "spline", "ksmooth", "smoothSpl"),
         nodes=5001L)

## S3 method for class 'DVHLst'
getDMEAN(x, interp=c("linear", "spline", "ksmooth", "smoothSpl"),
         nodes=5001L)

## S3 method for class 'DVHLstLst'
getDMEAN(x, interp=c("linear", "spline", "ksmooth", "smoothSpl"),
         nodes=5001L)

Arguments

Value

A data frame with the following value(s).

patID

Patient ID.

structure

Structure name.

doseMin

Minimum dose.

doseMax

Maximum dose.

doseAvg

Mean dose.

doseMed

Median dose.

doseSD

Dose standard deviation.

doseMode

Dose mode.

doseAvgTPS

Mean dose as exported from the TPS (if available).

doseMedTPS

Median dose as exported from the TPS (if available).

doseMinTPS

Minimum dose as exported from the TPS (if available).

doseMaxTPS

Maximum dose as exported from the TPS (if available).

See Also

getMetric, convertDVHsmooth, approxfun, splinefun, smooth.spline, dpill, locpoly

Examples

getDMEAN(dataMZ[[1]], interp="linear")

2Gy fractions biologically equivalent dose (EQD2)

Description

Calculate dose in 2Gy fractions biologically equivalent dose according to the linear-quadratic model, assuming a homogeneous dose distribution within the volume.

Usage

getEQD2(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## Default S3 method:
getEQD2(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## S3 method for class 'DVHs'
getEQD2(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## S3 method for class 'DVHLst'
getEQD2(D=NULL, fd=NULL, fn=NULL, ab=NULL)

## S3 method for class 'DVHLstLst'
getEQD2(D=NULL, fd=NULL, fn=NULL, ab=NULL)

Arguments

Details

EQD2 is a special case of isoeffective dose calculation with fractional dose d2=2, see getIsoEffD. The calculation assumes a homogeneous dose distribution within the volume.

Value

Default method: A data frame with variables EQD2, fractDose, ab.

If D is some kind of DVH object, the same kind of object is returned with the individual dose values converted to EQD2.

References

IAEA, & ICRU. (2008). Relative biological effectiveness in ion-beam therapy (Tech. Rep. No. IAEA-TR 461). Vienna, Austria: IAEA (International Atomic Energy Agency) and ICRU (International Commission on Radiation Units and Measurements).

See Also

getBED, getIsoEffD

Examples

getEQD2(D=50, fd=2.5, ab=c(2, 3, 4))
getEQD2(dataMZ[[c(1, 1)]], fd=1.8, ab=3)

Generalized equivalent uniform dose (gEUD)

Description

Calculate generalized equivalent uniform dose (gEUD). May be based on EQD2.

Usage

getEUD(x, EUDa, EUDfd=NULL, EUDab=NULL, ...)

## S3 method for class 'DVHs'
getEUD(x, EUDa, EUDfd=NULL, EUDab=NULL, ...)

## S3 method for class 'DVHLst'
getEUD(x, EUDa, EUDfd=NULL, EUDab=NULL, ...)

## S3 method for class 'DVHLstLst'
getEUD(x, EUDa, EUDfd=NULL, EUDab=NULL, ...)

Arguments

Value

A data frame with variables EUD, patID, and structure.

References

Niemierko, A. (1999). A generalized concept of equivalent uniform dose. Medical Physics, 26(6), 1100.

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.

See Also

getEQD2, getMetric

Examples

getEUD(dataMZ[[1]], EUDa=2)

# based on EQD2
getEUD(dataMZ[[1]], EUDa=2, EUDfd=1.8, EUDab=4)

Isoeffective dose calculation

Description

Convert given (fractional) dose into a corresponding (fractional) dose for a different total dose / fractionation schedule according to the linear-quadratic model.

Usage

getIsoEffD(D1=NULL, D2=NULL, fd1=NULL, fd2=NULL, ab=NULL)

## Default S3 method:
getIsoEffD(D1=NULL, D2=NULL, fd1=NULL, fd2=NULL, ab=NULL)

## S3 method for class 'DVHs'
getIsoEffD(D1=NULL, D2=NULL, fd1=NULL, fd2=NULL, ab=NULL)

## S3 method for class 'DVHLst'
getIsoEffD(D1=NULL, D2=NULL, fd1=NULL, fd2=NULL, ab=NULL)

## S3 method for class 'DVHLstLst'
getIsoEffD(D1=NULL, D2=NULL, fd1=NULL, fd2=NULL, ab=NULL)

Arguments

Details

DVH methods: Calculate D2 based on D1, fd1, fd2, and ab. The default method can also calculate fd2 based on D1, D2, fd1, and ab.

Value

The (vector of) corresponding (fractional) dose value(s). If D is some kind of DVH object, the same kind of object is returned with the individual dose values converted to D2.

References

IAEA, & ICRU. (2008). Relative biological effectiveness in ion-beam therapy (Tech. Rep. No. IAEA-TR 461). Vienna, Austria: IAEA (International Atomic Energy Agency) and ICRU (International Commission on Radiation Units and Measurements).

See Also

getBED, getEQD2

Examples

# reference: 70Gy in 2Gy fractions
# new fractionation: 3Gy fractions
# calculate corresponding dose
(D2 <- getIsoEffD(D1=70, fd1=2, fd2=3, ab=c(3.5, 10)))

getIsoEffD(D1=dataMZ[[c(1, 1)]], fd1=1.8, fd2=2, ab=3.5)

Point-wise mean DVH with point-wise SDs

Description

Returns the point-wise mean and median DVH with the point-wise standard deviation for a given list of input DVHs. Other point-wise measures may be calculated as well.

Usage

getMeanDVH(x, fun=list(mean=mean, median=median, sd=sd),
           cumul=TRUE, thin=1, byPat=TRUE, patID=NULL, structure=NULL,
           fixed=TRUE, returnDVHObj=FALSE)

## S3 method for class 'DVHs'
getMeanDVH(x, fun=list(mean=mean, median=median, sd=sd),
           cumul=TRUE, thin=1, byPat=TRUE, patID=NULL, structure=NULL,
           fixed=TRUE, returnDVHObj=FALSE)

## S3 method for class 'DVHLst'
getMeanDVH(x, fun=list(mean=mean, median=median, sd=sd),
           cumul=TRUE, thin=1, byPat=TRUE, patID=NULL, structure=NULL,
           fixed=TRUE, returnDVHObj=FALSE)

## S3 method for class 'DVHLstLst'
getMeanDVH(x, fun=list(mean=mean, median=median, sd=sd),
           cumul=TRUE, thin=1, byPat=TRUE, patID=NULL, structure=NULL,
           fixed=TRUE, returnDVHObj=FALSE)

Arguments

Details

Before calculating the point-wise mean and SD, DVHs in x are first linearly interpolated with convertDVH using the same set of nodes.

Value

By default (returnDVHObj=FALSE) returns a data frame with point-wise mean DVH averaged over structures (byPat=TRUE) or over patients (byPat=FALSE) including the point-wise standard deviation or other measures as controlled by fun. With returnDVHObj=TRUE, a DVH object is returned that is equivalent to a DVH as imported from a file. In particular, functions like showDVH or getMetric can be used on such an object.

See Also

showDVH, convertDVH

Examples

res1 <- getMeanDVH(dataMZ, byPat=TRUE, structure=c("HEART", "AMYOCL"))
head(res1)

# average differential DVHs
# matches patients P123 and P234
res2 <- getMeanDVH(dataMZ, fun=list(min=min, max=max),
                   cumul=FALSE, byPat=FALSE,
                   patID="23", fixed=FALSE)
head(res2)

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

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.

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.

See Also

saveMetric, getEUD, getNTCP, getTCP, getEQD2, approxfun, splinefun, dpill, locpoly

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

Normal tissue complication probability (NTCP)

Description

Calculate normal tissue complication probability (NTCP) from Lyman's probit model, Niemierko's logit model, the Poisson model, or the Kaellman relative seriality model. May be based on EQD2.

Usage

getNTCP(x,
        NTCPtd50=NULL, NTCPm=NULL, NTCPn=NULL, NTCPgamma50=NULL, NTCPs=NULL,
        EUDa=NULL, EUDfn=NULL, EUDab=NULL,
        NTCPtype=c("probit", "logit", "poisson", "relative_seriality"), ...)

## S3 method for class 'DVHs'
getNTCP(x,
        NTCPtd50=NULL, NTCPm=NULL, NTCPn=NULL, NTCPgamma50=NULL, NTCPs=NULL,
        EUDa=NULL, EUDfn=NULL, EUDab=NULL,
        NTCPtype=c("probit", "logit", "poisson", "relative_seriality"), ...)

## S3 method for class 'DVHLst'
getNTCP(x,
        NTCPtd50=NULL, NTCPm=NULL, NTCPn=NULL, NTCPgamma50=NULL, NTCPs=NULL,
        EUDa=NULL, EUDfn=NULL, EUDab=NULL,
        NTCPtype=c("probit", "logit", "poisson", "relative_seriality"), ...)

## S3 method for class 'DVHLstLst'
getNTCP(x,
        NTCPtd50=NULL, NTCPm=NULL, NTCPn=NULL, NTCPgamma50=NULL, NTCPs=NULL,
        EUDa=NULL, EUDfn=NULL, EUDab=NULL,
        NTCPtype=c("probit", "logit", "poisson", "relative_seriality"), ...)

Arguments

Details

For the logit, probit, and Poisson method, gEUD is used for DVH reduction. This is equivalent to the Kutcher-Burman DVH reduction scheme. The probit model is given in equation (1), the logit model in eqation (2), and the Poisson model in equation (3) in Kaellman (1992), with gEUD plugged in for D. The relative seriality model is given in equation (18).

Value

A data frame with variables NTCP, patID, and structure.

References

Kaellman, P., Agren, A., & Brahme, A. (1992). Tumor and normal tissue responses to fractionated non-uniform dose delivery. International Journal of Radiation Biology, 62(2), 249-262.

Kutcher, G. J., Burman, C., Brewster L., Goitein, M., & Mohan, R. (1991). Histogram reduction method for calculating complication probabilities for threedimensional treatment planning evaluations. International Journal of Radiation Oncology Biology Physics, 21(1), 137-146.

Lyman, J. T. (1985). Complication probability as assessed from dose volume histograms. Radiation Research, 104(2), S13-19.

Niemierko, A. (1999). A generalized concept of equivalent uniform dose. Medical Physics, 26(6), 1100.

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.

See Also

getTCP, getEUD, getMetric

Examples

## treatment was in 2 Gy fractions
getNTCP(dataMZ[[1]][["HEART"]],
        NTCPtd50=48, NTCPm=0.6, NTCPn=0.5, NTCPtype="probit")

getNTCP(dataMZ[[1]][["HEART"]],
        NTCPtd50=52.3, NTCPgamma=1.28, NTCPs=1, NTCPtype="relative_seriality")

Tumor control probability (TCP)

Description

Calculate tumor control probability (TCP) from Lyman's probit model, Niemierko's logit model, the Poisson model, or the Kaellman relative seriality model. May be based on EQD2.

Usage

getTCP(x, TCPtcd50=NULL, TCPm=NULL, TCPn=NULL, TCPgamma50=NULL, NTCPs=NULL,
       EUDa=NULL, EUDfn=NULL, EUDab=NULL,
       TCPtype=c("probit", "logit", "poisson", "relative_seriality"), ...)

Arguments

Details

For the logit, probit, and Poisson method, gEUD is used for DVH reduction. This is equivalent to the Kutcher-Burman DVH reduction scheme. The probit model is given in equation (1), the logit model in eqation (2), and the Poisson model in equation (3) in Kaellman (1992), with gEUD plugged in for D. The relative seriality model is given in equation (18).

Value

A data frame with variables TCP, patID, and structure.

References

Kaellman, P., Agren, A., & Brahme, A. (1992). Tumor and normal tissue responses to fractionated non-uniform dose delivery. International Journal of Radiation Biology, 62(2), 249-262.

Kutcher, G. J., Burman, C., Brewster L., Goitein, M., & Mohan, R. (1991). Histogram reduction method for calculating complication probabilities for threedimensional treatment planning evaluations. International Journal of Radiation Oncology Biology Physics, 21(1), 137-146.

Lyman, J. T. (1985). Complication probability as assessed from dose volume histograms. Radiation Research, 104(2), S13-19.

Niemierko, A. (1999). A generalized concept of equivalent uniform dose. Medical Physics, 26(6), 1100.

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.

See Also

getNTCP, getEUD, getMetric

Examples

getTCP(dataMZ[[1]],
       TCPtcd50=40, TCPm=0.6, TCPn=0.5, TCPtype="probit")

Merge existing DVH objects

Description

Combine several existing DVH objects into one object.

Usage

mergeDVH(...)

Arguments

Details

The first object determines whether the resulting object is organized by patient or by structure. Objects need not originally come from the same treatment planning system.

Value

Returns an object of class DVHLstLst.

Examples

## Not run: 
# pick some DVH files interactively
a <- readDVH(type="Cadplan")

# pick other DVH files interactively
b <- readDVH(type="Eclipse")

# combine DVH data
res <- mergeDVH(a, b)
res

## End(Not run)

Print basic information about one or more DVHs

Description

Print basic information (patients, structures, dose range) about one or more DVHs.

Usage

## S3 method for class 'DVHs'
print(x, ...)

## S3 method for class 'DVHLst'
print(x, ...)

## S3 method for class 'DVHLstLst'
print(x, ...)

Arguments

Value

Prints summary information about the DVHs.

See Also

readDVH

Examples

print(dataMZ)
print(dataMZ, verbose=TRUE)

Read constraint definitions from text file

Description

Reads the definition of quality assurance constraints from a text file.

Usage

readConstraint(x, ...)

Arguments

Details

This is a wrapper for read.table.

The text file should contain three columns with the column names patID, structure, constraint in the first line. Each further line then defines one constraint and the scope it applies to in terms of patients and structures. See checkConstraint for the definition of a constraint and for the definition of a scope. Example content:

"patID" "structure" "constraint"
"*" "HEART" "D1CC < 20Gy"
"234" "*" "V10% > 8CC"

Value

A data.frame with columns patID, structure, constraint that can be used in functions checkConstraint and showConstraint.

See Also

read.table, checkConstraint, saveConstraint, showConstraint

Examples

## Not run: 
readConstraint("constraint.txt")
readConstraint()

## End(Not run)

Read DVH text files

Description

Reads single or multiple DVH text files as exported from Varian Eclipse(TM), CadPlan(TM), OnCentra MasterPlan(TM), Philipps Pinnacle3 (TM), Elekta Monaco (TM), Tomo HiArt (TM), RaySearch Labs RayStation (TM), or Medcom ProSoma (TM). Supports cumulative and differential DVHs.

Usage

readDVH(x,
        type=c("Eclipse", "Cadplan", "Masterplan",
               "Pinnacle", "Monaco", "HiArt",
               "RayStation", "ProSoma", "PRIMO"),
        planInfo=FALSE, courseAsID=FALSE, add, ...)

Arguments

Details

Absolute dose values need to be given in Gy, cGy, or eV/g for uncalibrated dose in DVHs exported by PRIMO. Absolute volume values need to be given in in cm^3.

Differential DVHs are automatically converted to cumulative DVHs, but the differential DVH information is kept.

Sum plans are supported.

For Eclipse starting with version 13, the date format is locale dependent as it uses words for day and month. Importing those dates as class Date requires that the correct locale is set (see Sys.setlocale), and that files containing accents are read using the correct encoding (see above). Otherwise, date is stored as a character string.

For RayStation, only cumulative DVHs with absolute volume are currently supported. Volume is assumed to be measured in cm^3.

For files with absolute volume exported from Masterplan and Tomo HiArt, you can specify volume_from_dvh=TRUE if the structure volume should be guessed from the maximal volume given in the DVH for each structure.

Since files from HiArt, ProSoma and PRIMO do not contain info on patient ID, the current workaround is to generate a random ID.

To export data from Tomo HiArt, copy to clipboard and then save to file from a text editor. Support for Tomo HiArt files is currently limited to those with absolute dose. Please send an anonymized sample file if you need to read files with relative dose. You can provide a list hiart with more information about patients and structures. The list should have one component for each file you import. Each component itself has to be a named list with optional components

• date - a character string like "2022-01-16" for the date

• patName - a character string for patient name

• patID - a character string for patient ID

• doseRx - a character string like "50.4Gy" for prescription dose in the same dose unit as used in the DVHs

• structVol - a named character vector like c("PTV"=750, "LUNG"=1250) giving the absolute structure volumes with names equal to structure names

• volumeUnit - a character string, either "CC" or "cm3", for the structure volume unit)

The same approach can be used for RayStation files with a list raystation.

Pinnacle3 files have to be exported using its own scripting facility such that information from one patient is contained in one directory. A suitable export script is available on request from the package authors. The directory layout for one patient has to be as follows (experimental, likely to change in future versions):

• Files (CSV format with column headers):

  • DoseInfo.csv (variables "PrescriptionDose cGy", "NumberOfFractions", "Dosis cGy")

  • PatInfo.csv (variables "LastName", "FirstName", "MedicalRecordNumber")

  • PlanInfo.csv (variable "PlanName")

• Directory: Data:

  • Info.csv (variables "Filename", "RegionOfInterestName", "DoseMin cGy", "DoseMax cGy", "DoseMean cGy", "Volume ccm")

  • DVH1.csv, DVH2.csv, ... - the actual DVH data files with names defined in Info.csv variable "Filename". They should look like ⁠NumberOfDimensions = 2; NumberOfPoints = 431; Points[] ={ 0,0 10,0 ... 4000,100 }; ⁠

Value

Returns an object of class DVHLstLst. This is a list (one component with class DVHLst for each original file from one patient) of lists (each component is an object of class DVHs). A DVHs object is a list with the following components:

dvh

matrix - cumulative DVH values

dvhDiff

matrix - differential DVH values, only created a) if original file contained a differential DVH or b) by convertDVH

patID

character string - patient ID

date

character string - date of DVH export

type

character string - cumulative or differential DVH

plan

character string - plan name

course

character string - course - currently Eclipse only

structure

character string - structure name

structVol

numeric - structure volume

doseUnit

character string - measurement unit dose

volumeUnit

character string - measurement unit volume

doseRx

numeric - prescription dose

isoDoseRx

numeric - iso-dose percentage

doseMin

numeric - minimum dose from DVH file

doseMax

numeric - maximum dose from DVH file

doseAvg

numeric - average dose from DVH file

doseMed

numeric - median dose from DVH file

doseSD

numeric - dose standard deviation from DVH file

See Also

Sys.glob, readLines, print.DVHs, showDVH, getMetric, checkConstraint, convertDVH

Examples

## Not run: 
# pick DVH files interactively
res <- readDVH()
res

# read all txt files in subdirectory DVH
res <- readDVH("DVH/*.txt", type="Eclipse")
res

## End(Not run)

Open web-based GUI in browser

Description

Opens the web-based GUI in an external browser.

Usage

runGUI(...)

Arguments

Details

This function calls runApp to run the included DVHshiny application. See vignette("DVHshiny") for documentation.

See Also

runApp

Examples

## Not run: 
runGUI()

## End(Not run)

Save constraint result to file

Description

Saves results from checkConstraint to a text file.

Usage

saveConstraint(x, ...)

Arguments

Details

This is a wrapper for write.table.

See Also

write.table, checkConstraint

Examples

res <- checkConstraint(dataMZ, c("D10CC < 10Gy", "V20Gy < 20%"))
## Not run: 
saveConstraint(res, file="constrResults.txt", sep="\t")

## End(Not run)

Save DVH diagram to file

Description

Saves one or multiple DVH diagrams to file.

Usage

saveDVH(x, file="", ...)

Arguments

Details

This is a wrapper for ggsave.

Value

If x is a list of ggplot objects, one file is written for each list component. If x is a single ggplot object, one file is written.

See Also

ggsave, showDVH, showConstraint

Examples

res <- showDVH(dataMZ, byPat=TRUE, structure=c("HEART", "AMYOCL"))
## Not run: 
saveDVH(res, "out.pdf")

## End(Not run)

Save DVH metrics to file

Description

Saves results from getMetric to a text file.

Usage

saveMetric(x, file = "", ...)

## S3 method for class 'data.frame'
saveMetric(x, file = "", ...)

## S3 method for class 'list'
saveMetric(x, file = "", ...)

Arguments

Details

This is a wrapper for write.table.

Value

If x is a list, one text file is written for each list component. If x is a data.frame, one file is written.

See Also

write.table, getMetric

Examples

res <- getMetric(dataMZ, c("D1CC", "V10%_CC"),
                 sortBy=c("metric", "structure"),
                 splitBy="patID")
## Not run: 
# not run
saveMetric(res, file="metricsResults.txt", sep="\t")

## End(Not run)

Display constraints for cumulative dose-volume histograms

Description

Displays quality assurance constraints for cumulative dose-volume histograms: Either one diagram per patient - including multiple structures. Or one diagram per structure - including multiple patients.

Usage

showConstraint(x, constr, byPat=TRUE, rel=TRUE, guessX=TRUE, guessY=TRUE,
               thresh=1, show=TRUE, visible=FALSE)

## S3 method for class 'DVHs'
showConstraint(x, constr, byPat=TRUE, rel=TRUE, guessX=TRUE, guessY=TRUE,
               thresh=1, show=TRUE, visible=FALSE)

## S3 method for class 'DVHLst'
showConstraint(x, constr, byPat=TRUE, rel=TRUE, guessX=TRUE, guessY=TRUE,
               thresh=1, show=TRUE, visible=FALSE)

## S3 method for class 'DVHLstLst'
showConstraint(x, constr, byPat=TRUE, rel=TRUE, guessX=TRUE, guessY=TRUE,
               thresh=1, show=TRUE, visible=FALSE)

Arguments

Details

Constraints are shown as points in the cumulative DVH with an additional arrow indicating where the cumulative DVH curve should lie relative to the constraint. On each DVH curve, the point with the minimal Euclidean distance to the constraint is indicated. Note that, visually, this point only has the minimal apparent distance if the aspect ratio of the diagram is 1.

If multiple diagrams are produced, they are shown in the same graphics device. If interactive inspection is required, make sure you use an R development environment that saves previous diagrams and allows navigating between them - e.g., RStudio or OpenAnalytics Architect.

Value

Silently returns a ggplot diagram object, or - when multiple diagrams are constructed - a list of ggplot diagram objects.

See Also

checkConstraint, saveDVH

Examples

data(dataMZ)

# define constraints
constr <- data.frame(
    patID=c("P123", "P234"),
    structure=c("HEART", "*"),
    constraint=c("D1CC < 20Gy", "V10% > 8CC"),
    stringsAsFactors=FALSE)       # this is important
showConstraint(dataMZ, constr=constr, byPat=FALSE)

Display dose volume histograms

Description

Displays dose volume histograms: Either one diagram per patient - including multiple structures. Or one diagram per structure - including multiple patients.

Usage

showDVH(x, cumul=TRUE, byPat=TRUE, patID=NULL, structure=NULL,
        rel=TRUE, guessX=TRUE, guessY=TRUE, thresh=1, addMSD=FALSE,
        show=TRUE, visible=FALSE, fixed=TRUE)

## S3 method for class 'DVHs'
showDVH(x, cumul=TRUE, byPat=TRUE, patID=NULL, structure=NULL,
        rel=TRUE, guessX=TRUE, guessY=TRUE, thresh=1, addMSD=FALSE,
        show=TRUE, visible=FALSE, fixed=TRUE)

## S3 method for class 'DVHLst'
showDVH(x, cumul=TRUE, byPat=TRUE, patID=NULL, structure=NULL,
        rel=TRUE, guessX=TRUE, guessY=TRUE, thresh=1, addMSD=FALSE,
        show=TRUE, visible=FALSE, fixed=TRUE)

## S3 method for class 'DVHLstLst'
showDVH(x, cumul=TRUE, byPat=TRUE, patID=NULL, structure=NULL,
        rel=TRUE, guessX=TRUE, guessY=TRUE, thresh=1, addMSD=FALSE,
        show=TRUE, visible=FALSE, fixed=TRUE)

Arguments

Details

If multiple diagrams are produced, they are shown in the same graphics device. If interactive inspection is required, make sure you use an R development environment that saves previous diagrams and allows navigating between them - e.g., RStudio or OpenAnalytics Architect.

For addMSD=TRUE, the number of DVH nodes (dose values) is reduced by 1/3 of the maximum number of nodes in x. Before calculating the point-wise mean and SD, DVHs in x are first linearly interpolated using the same set of nodes.

Value

Silently returns a ggplot diagram object, or - when multiple diagrams are constructed - a list of ggplot diagram objects.

See Also

ggplot, readDVH, saveDVH, getMeanDVH

Examples

showDVH(dataMZ, byPat=TRUE, structure=c("HEART", "AMYOCL"))

# matches patients P123 and P234
showDVH(dataMZ, byPat=FALSE, patID="23", fixed=FALSE)

Show average dose volume histograms

Description

Displays average dose volume histograms grouped by patients or structures.

Usage

showMeanDVH(x, byPat=TRUE, patID=NULL, structure=NULL,
            rel=TRUE, guessX=TRUE, thresh=1, show=TRUE, fixed=TRUE,
            showSD=TRUE, color=TRUE, facet=TRUE)

Arguments

Details

TODO

Value

Silently returns a ggplot diagram object, or - when multiple diagrams are constructed - a list of ggplot diagram objects.

See Also

ggplot, showDVH, getMeanDVH

Examples

# mean DVH for HEART and AMYOCL averaged over patients
res <- getMeanDVH(dataMZ, byPat=FALSE, structure=c("HEART", "AMYOCL"))
showMeanDVH(res)