Prescription¶
Define Prescription
and methods for parsing prescription data
from python objects as well as JSON- or YAML-formatted files.
Parsing methods expect the following formats.
YAML:
- name : PTV
label : 1
is_target: Yes
dose : 35.
constraints:
- "D90 >= 32.3Gy"
- "D1 <= 1.1rx"
- name : OAR1
label : 2
is_target: No
dose :
constraints:
- "D95 <= 20Gy"
- "V30 Gy <= 20%"
Python list
of dict
(JSON approximately the same):
[{
"name" : "PTV",
"label" : 1,
"is_target" : True,
"dose" : 35.,
"constraints" : ["D1 <= 1.1rx", "D90 >= 32.3Gy"]
}, {
"name" : "OAR1",
"label" : 2,
"is_target" : False,
"dose" : None,
"constraints" : ["D95 <= 20Gy"]
}]
- JSON verus Python syntax differences:
true
/false
instead ofTrue
/False
null
instead ofNone
-
class
prescription.
Prescription
(prescription_data=None)[source]¶ Class for specifying structures with dose targets and constraints.
-
add_structure_to_dictionaries
(structure)[source]¶ Add a new structure to internal representation of prescription.
Parameters: structure ( Structure
) – Structure added toPrescription.structure_dict
. An corresponding, empty constraint list is added toPrescription.constraint_dict
.Returns: None Raises: TypeError
– Ifstructure
not aStructure
.
-
constraints_by_label
¶ Dictionary of constraints in prescription, by structure label.
-
dict
¶ Dictionary of structures in prescription, by label.
-
digest
(prescription_data)[source]¶ Populate
Prescription
‘s structures and dose constraints.Specifically, for each entry in
prescription_data
, construct aStructure
to capture structure data (e.g., name, label), as well as a corresponding but separateConstraintList
object to capture any dose constraints specified for the structure.Add each such structure to
Prescription.structure_dict
, and each such constraint list toPrescription.constraint_dict
. Build or copy a “list of dictionaries” representation of the prescription data, assign toPrescription.rx_list
.Parameters: prescription_data – Input to be parsed for structure and dose constraint data. Accepted formats include str
specifying a valid path to a suitably-formatted JSON or YAML file, or a suitably-formattedlist
ofdict
objects.Returns: None Raises: TypeError
– If input not of typelist
or astr
specfying a valid path to file that can be loaded with thejson.load()
oryaml.safe_load()
methods.
-
list
¶ List of structures in prescription
-
report
(anatomy)[source]¶ Reports whether
anatomy
fulfills all prescribed constraints.Parameters: anatomy ( Antomy
) – Container of structures to compare against prescribed constraints.Returns: Dictionary keyed by structure label, with data on each dose constraint associated with that structure in this Prescription
. Reported data includes the constraint, whether it was satisfied, and the actual dose achieved at the percentile/threshold specified by the constraint.Return type: dict
Raises: TypeError
– Ifanatomy
not anAnatomy
.
-
-
prescription.
d_strip
(input_string)[source]¶ Strip ‘d’, and ‘D’ from input string.
Preprocessing step for handling of string constraints of type “D70 < 20 Gy”.
-
prescription.
eval_constraint
(string_constraint, rx_dose=None)[source]¶ Parse input string to form a new
Constraint
instance.This method handles the following input cases.
- Absolute dose constraints:
- “min > x Gy”
- variants: “Min”, “min”
- meaning: minimum dose greater than x Gy
- “mean < x Gy” (“mean > x Gy”)
- variants: “Mean, mean”
- meaning: mean dose less than (more than) than x Gy
- “max < x Gy”
- variants: “Max”, “max”
- meaning: maximum dose less than x Gy
- “D __ < x Gy” (“D __ > x Gy”)
- variants: “D __%”, “d __%”, “D __”, “d __”
- meaning: dose to __ percent of volume less than (greater than) x Gy
- “V __ Gy < p %” (“V __ Gy > p %”)
- variants: “V __”, “v __”, “__ Gy to”, “__ to”
- meaning: no more than (at least) __ Gy to p percent of volume.
- Relative dose constraints:
- “V __ %rx < p %” (“V __ %rx > p %”)
- variants: “V __%”, “v __%”, “V __”, “v __”
- meaning: at most (at least) p percent of structure receives __ percent of rx dose.
- “D __ < {frac} rx”, “D __ > {frac} rx”
- variants: “D __%”, “d __%”, “D __”, “d __”
- meaning: dose to __ percent of volume less than (greater than) frac * rx
- Absolute volume constraints:
- “V __ Gy > x cm3” (“V __ Gy < x cm3”), “V __ rx > x cm3” (“V __ rx < x cm3”)
- variants: “cc” vs. “cm3” vs. “cm^3”; “V __ _” vs. “v __ _”
- error: convert to relative volume terms
Parameters: - string_constraint (
str
) – Parsable string representation of dose constraint. - rx_dose (
DeliveredDose
, optional) – Prescribed dose level to associate with dose constraint, required for relative dose constraints.
Returns: Dose constraint specified by input.
Return type: Constraint
Raises: TypeError
– Ifrx_dose
not of typeDeliveredDose
.ValueError
– If input string specifies an absolute volume constraint, or if input is not well-formed (e.g., a dose quantity appears on LHS and RHS of inequality).