DVHmetrics (version 0.3.1)

checkConstraint: 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

x

A single DVH (object of class DVHs), multiple DVHs from one patient/structure (object of class DVHLst), or multiple DVHs from many patients/structures (object of class DVHLstLst). See

constr

One or more constraints - given as a character vector or as a data.frame. See Details.

byPat

Relevant if multiple DVHs are given. If x has class DVHLst: byPat=TRUE means that the DVHs are for one patient with multiple structures. byPat=FALSE means that the DVHs are for one structure from multipl

semSign

Meaning of the sign of the observed dose/volume differences between DVHs and constraints. semSign=TRUE means that negative differences indicate constraint compliance, positive differences indicate constraint violations. With semSign=FAL

sortBy

character vector. Sorting criteria for the output data frame.

interp

character. Method of interpolation between DVH points: Linear interpolation using approx, monotone Hermite spline interpolation using spline

...

Additional parameters passed to getMetric. Use for constraints on EUD (see getEUD for parameter names), TCP (see

Value

• A data frame with details on constraint compliance / violation.
• patID
  Patient ID
• structure
  Structure
• constraint
  The checked constraint
• observed
  The observed value for the metric given in the constraint
• compliance
  Does the DVH satisfy the constraint?
• deltaV
  Volume difference between constraint and observed DVH (for the constraint dose) in measurement unit specified by constraint
• deltaVpc
  Percent volume difference between constraint and observed DVH (for the constraint dose) relative to constraint volume
• deltaD
  Dose difference between constraint and observed DVH (for the constraint volume) in measurement unit specified by constraint
• deltaDpc
  Percent dose difference between constraint and observed DVH (for the constraint volume) relative to constraint dose
• dstMin
  Minimal Euclidean distance between constraint and the cumulative DVH, using linear interpolation
• ptMinD
  Dose coordinate of closest point on cumulative DVH to constraint
• ptMinV
  Volume coordinate of closest point on cumulative DVH to constraint

Details

A DVH constraint is a character string that consists of three parts: The DVH metric, the comparison operator (<, >, <=< code="">, >=), 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 inx,constrcan be acharactervector with elements like the examples above.
• If constraints apply only to some patients/structures,constrmust be a data frame with variablesconstraint,patIDandstructure. Each row then defines one constraint and its scope:constraintmust be a character string with one constraint definition as in the examples above.patIDmust be either a character string with a valid patient ID or"*"if the the constraint applies to all patients.structuremust be either a character string with a valid structure or"*"if the the constraint applies to all structures. If variablepatIDis missing from the data frame, the constraints apply to all available patients. If variablestructureis missing from the data frame, the constraints apply to all available structures. SeereadConstraintfor reading appropriate constraintdata.framesfrom 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.

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)