Dose Constraints¶
Define Constraint
base class, along with specializations
MaxConstraint
, MinConstraint
, MeanConstraint
and PercentileConstranint
. Also define ConstraintList
container and function D()
for instantiating constraints with a
syntax used by clinicians, e.g.:
D('max') < 30 * Gy
D('min') > 20 * Gy
D('mean') > 25 * Gy
D(90) > 22 * Gy
D(5) < 29 * Gy
Also define the DVH
(dose volume histogram) object for
converting structure dose vectors to plottable DVH data sets.
- Atrributes:
- RELOPS (
__ConstraintRelops
): Defines constants RELOPS.GEQ
,RELOPS.LEQ
, andRELOPS.INDEFINITE
for categorizing inequality constraint directions.
- RELOPS (
-
class
dose.
Constraint
[source]¶ Base class for dose constraints.
The
MinConstraint
,MaxConstraint
,MeanConstraint
andPercentileConstraint
types all inherit fromConstraint
. This class defines all the basic getters and setters for constraint properties such as the type of threshold, constraint direction (relop) and dose bound, as well as other shared properties such as slack and dual values relevant to theConstraint
object’s role in treatment plan optimization problems.-
__eq__
(other)[source]¶ Overload operator ==
Define comparison between constraints by comparing their relops, doses and thresholds.
Parameters: ( (other) – class:’Constraint’): Value to be compared. Returns: obj:bool: True
if compared constraints are equivalent.Raises: TypeError
– Ifother
is not aConstraint
.
-
__gt__
(other)[source]¶ Overload operator >.
Enable
Constraint.dose
andConstraint.relop
to be set via syntax ‘constraint > dose’.Parameters: other – Value that Constraint.dose
will be set to.Returns: Updated version of this object. Return type: Constraint
-
__lt__
(other)[source]¶ Overload operator <.
Enable
Constraint.dose
andConstraint.relop
to be set via syntax ‘constraint < dose’.Parameters: other – Value that Constraint.dose
will be set to.Returns: Updated version of this object. Return type: Constraint
-
__str__
()[source]¶ Stringify
Constraint
as ‘D{threshold} {<= or >=} {dose}’
-
active
¶ True if constraint active in most recent plan that used it.
-
dose
¶ Dose bound for constraint.
Getter returns dose in absolute terms (i.e.,
DeliveredDose
units.)Setter accepts dose in absolute or relative terms. That is, dose may be provided provided in units of
Percent
or in units ofDeliveredDose
, such asGray
.Raises: TypeError
– Ifdose
not of allowed types.
-
dose_achieved
¶ Constraint dose +/- slack.
-
dual_value
¶ Value of dual variable associated with constraint.
This property is intended to reflect information about the state of the
Constraint
in the context of the most recent run of an optimization problem that it was used in. Accordingly, it is to be managed by some client(s) of theConstraint
and not the object itself.In particular, this property is meant to hold the value of the dual variable associated with the dose constraint in some solver’s representation of an optimization problem, and the value should be that attained at the conclusion of a solver run.
-
priority
¶ Constraint priority.
Priority is one of {
0
,1
,2
,3
}. Constraint priorities are used when incorporating aConstraint
in an optimization problem with slack allowed.Priority
0
indicates that the constraint should be enforced strictly even when the overall problem formulation permits dose constraint slacks.The remaining values (
1
,2
, and3
) represent ranked tiers; slacks are permitted and penalized according to the priority: the slack variable for aPriority 1
constraint is penalizeed more heavily than that of aPriority 2
constraint, which is in turn penalized more heavily than the slack variable associated with aPriority 3
constraint. This mechanism allows users to encourage some constraints to be met more closely than others, even when slack is allowed for all of them.Raises: TypeError
– Ifpriority
not anint
:.ValueError
– Ifpriority
not in {0
,1
,2
,3
}.
-
relop
¶ Constraint relop (i.e., sense of inequality).
Should be one of
<
,>
,<=
, or>=
.The setter method does not differentiate between strict and non-strict inequalities (i.e.,
<
versus<=
), but both syntaxes are allowed for convenience.Raises: Value Error – If user tries to build a maximum dose constraint with a lower dose bound or a minimum dose constraint with an upper dose bound, or if relop
is not one of the expected string values.
-
resolved
¶ Indicator that constraint is complete and well-formed.
-
rx_dose
¶ Prescription dose associated with constraint.
This property is optional, but required when the
Constraint.dose
is phrased in relative terms (i.e., of typePercent
). It provides the numerical basis on which to interpret the relative value ofConstraint.dose
.Raises: TypeError
– Ifrx_dose
is not of typeDeliveredDose
, e.g.,Gray
orcentiGray
.
-
slack
¶ Value of slack variable associated with constraint.
This property is intended to reflect information about the state of the
Constraint
in the context of the most recent run of an optimization problem that it was used in. Accordingly, it is to be managed by some client(s) of theConstraint
and not the object itself.In particular, this property is meant to hold the value of the slack variable associated with the dose constraint in some solver’s representation of an optimization problem, and the value should be that attained at the conclusion of a solver run.
Raises: TypeError
– Ifslack
is not anint
orfloat
.ValueError
– Ifslack
is negative.
-
symbol
¶ Strict inequality
str
ofConstraint.relop
.
-
threshold
¶ Constraint threshold—percentile, min, max or mean.
-
upper
¶ Indicator of upper dose constraint (or, ‘less than’ inequality).
Parameters: None – Returns: True
if constraint of type “D(threshold) < dose”.Return type: bool
Raises: ValueError
– IfConstraint.relop
is not set.
-
-
class
dose.
ConstraintList
[source]¶ Container for
Constraint
objects.-
items
¶ dict
Dictionary of constraints in container, keyed by hashed values generated upon addition of constraint to container.
-
last_key
¶ Key generated upon most recent addition of a constraint to the container.
-
__iadd__
(other)[source]¶ Overload operator +=.
Enable syntax
ConstraintList
+=Constraint
.Parameters: other – Singleton, or iterable collection of Constraint
objects to append to thisConstraintList
.Returns: Updated version of this object. Return type: ConstraintList
Raises: TypeError
– Ifother
is not aConstraint
or iterable collection of constraints.
-
__isub__
(other)[source]¶ Overload operator -=.
- Enables syntaxes
ConstraintList
-=Constraint
, andConstraintList
-=key
.
Remove
other
from thisConstraintList
if it is a key with a correspondingConstraint
, or if it is aConstraint
for which an exactly equivalentConstraint
is found in the list.Parameters: other – Constraint
or key to aConstraint
to be removed from thisConstraintList
.Returns: Updated version of this object. Return type: ConstraintList
-
clear
()[source]¶ Clear constraints from
ConstraintList
.Parameters: None – Returns: None
-
contains
(constr)[source]¶ Test whether search
Constraint
exists in thisConstraintList
.Parameters: constr ( Constraint
) – Search term.Returns: True
if aConstraint
equivalent toconstr
found in thisConstraintList
.Return type: bool
-
keys
¶ Keys of constraints in list.
-
list
¶ list
ofConstraint
objects inConstraintList
.
-
mean_only
¶ True
if list exclusively contains mean constraints.
-
plotting_data
¶ List of
matplotlib
-compatible data for all constraints.
-
size
¶ Number of constraints in list.
-
-
dose.
D
(threshold, relop=None, dose=None)[source]¶ Utility for constructing dose constraints with clinical syntax.
Parameters: - threshold – Specify type of dose constraint; if real-valued or
of type
Percent
, parsed as a percentile constraint. If string-valued, tentatively interpreted as a mean, minimum, or maximum type dose constraint. - relop (optional) – Sense of inequality. Expected to be compatible
with
Constraint.relop
setter. - dose (optional) – Dose bound. Expected to be compatible with
Constraint.dose
setter.
Returns: Return type depends on argument
threshold
.Return type: Raises: ValueError
– Ifthreshold
does not conform to expected types or formats.Examples
>>> D('mean') > 30 * Gy >>> D('min') > 10 * Gy >>> D('max') < 5 * Gy >>> D(30) < 4 * Gy >>> D(90) > 47 * Gy
- threshold – Specify type of dose constraint; if real-valued or
of type
-
class
dose.
DVH
(n_voxels, maxlength=1000)[source]¶ Representation of a dose volume histogram.
Given a vector of doses, the
DVH
object generates the corresponding dose volume histogram (DVH).A DVH is associated with a planning structure, which will have a finite volume or number of voxels. A DVH curve (or graph) is a set of points \((d, p)\)—with \(p\) in the interval \([0, 100]\)–where for each dose level \(d\), the value \(p\) gives the percent of voxels in the associated structure receiving a radiation dose \(\ge d\).
Sampling is performed if necessary to keep data series length short enough to be conveniently transmitted (e.g., as part of an interactive user interface) and plotted (e.g., with
matplotlib
utilities) with low latency.Note that the set of (dose, percentile) pairs are maintained as two sorted, length-matched, vectors of dose and percentile values, respectively.
-
MAX_LENGTH
¶ int
Default maximum length constant to use when constructing and possibly sampling DVH cures.
-
data
¶ Sorted dose values from DVH curve.
The data provided to the setter are sorted to form the abscissa values for the DVH curve. If the length of the input exceeds the maximum data series length (as determined when the object was initialized), the input data is sampled.
Raises: ValueError
– If size of input data does not match size of- structure associated with
DVH
as specified to - object initializer.
-
dose_at_percentile
(percentile)[source]¶ Read off DVH curve to get dose value at
percentile
.Since the
DVH
object maintains the DVH curve of (dose, percentile) pairs as two sorted vectors, to approximate the the dose d at percentilepercentile
, we retrieve the index i that yields the nearest percentile value. The corresponding i’th dose is returned. When the nearest percentile is not within 0.5%, the two nearest neighbor percentiles and two nearest neighbor dose values are used to approximate the dose at the queried percentile by linear interpolation.Parameters: percentile ( int
,float
orPercent
) – Queried percentile for which to retrieve corresponding dose level.Returns: Dose value from DVH curve corresponding to queried percentile, or nan
if the curve has not been populated with data.
-
max_dose
¶ Largest dose value in DVH curve.
-
min_dose
¶ Smallest dose value in DVH curve.
-
percentile_at_dose
(dose)[source]¶ Read off DVH curve to get precentile value at
dose
.Parameters: dose ( int
,float
, orDeliveredDose
) – Quertied dose for which to retrieve the corresponding percentile. Assumed to have same units as DVH data.Returns: Percentile value from DVH curve corresponding to queried dose, or nan
if the curve has not been populated with data.
-
plotting_data
¶ Dictionary of
matplotlib
-compatible plotting data.
-
populated
¶ True if DVH curve is populated.
-
-
class
dose.
MaxConstraint
(relop=None, dose=None)[source]¶ Maximum dose constraint.
Extend base class
Constraint
. Express an upper bound on the maximum dose to a structure.-
plotting_data
¶ Dictionary of
matplotlib
-compatible data.
-
-
class
dose.
MeanConstraint
(relop=None, dose=None)[source]¶ Mean dose constraint.
Extend base class
Constraint
. Express an upper or lower bound on the mean dose to a structure.-
plotting_data
¶ Dictionary of
matplotlib
-compatible data.
-
-
class
dose.
MinConstraint
(relop=None, dose=None)[source]¶ Minimum dose constraint.
Extend base class
Constraint
. Express a lower bound on the minimum dose to a structure.-
plotting_data
¶ Dictionary of
matplotlib
-compatible data.
-
-
class
dose.
PercentileConstraint
(percentile=None, relop=None, dose=None)[source]¶ Percentile, i.e. dose-volume, or partial dose constraint.
Allow for dose bounds to be applied to a certain fraction of a structure involved in treatment planning. For instance, a lower constraint,
>>> # D80 > 60 Gy,
requires at least 80% of the voxels in a structure must receive 60 Grays or greater, and an upper constraint,
>>> # D25 < 5 Gy,
requires no more than 25% of the voxels in a structure to receive 25 Grays or greater.
Extend base class
Constraint
, recastConstraint.threshold
asPercentileConstraint.percentile
.-
get_maxmargin_fulfillers
(y, had_slack=False)[source]¶ Get indices to values of
y
deepest in feasible set.In particular, given
len(y)
, ifm
voxels are required to respect thisPercentileConstraint
exactly,y
is assumed to contain at leastm
entries that respect the constraint (for instance,y
is generated by a convex program that includes a convex restriction of the dose constraint).Procedure.
\[\begin{array}{rl} \mathbf{0.} & \mbox{Define} \\ & p = \mbox{percent non-violating} \cdot \mbox{structure size} = \mbox{percent non-violating} \cdot \mathbf{len}(y) \\ \mathbf{1.} & \mbox{Get margins: } y - \mbox{dose bound}. \\ \mathbf{2.} & \mbox{Sort margin indices by margin values.} \\ \mathbf{3.} & \mbox{If upper constraint, return indices of $p$ most negative entries}. \\ \mathbf{4.} & \mbox{If lower constraint, return indices of $p$ most positive entries}. \\ \end{array}\]Parameters: - y – Vector-like input data of length
m
. - had_slack (
bool
, optional) – Define margin relative to slack-modulated dose value instead of the base dose value of thisPercentileConstraint
.
Returns: Vector of indices that yield the
p
entries ofy
that fulfill thisPercentileConstraint
with the greatest margin.Return type: numpy.ndarray
- y – Vector-like input data of length
-
percentile
¶ Percentile threshold in interval (
0
,100
).Raises: TypeError
– Ifpercentile
is notint
,float
, orPercent
.
-
plotting_data
¶ Dictionary of
matplotlib
-compatible data.
-