Anatomy¶
Define Anatomy
, container for treatment planning structures.
-
class
anatomy.
Anatomy
(structures=None)[source]¶ Iterable container class for treatment planning structures.
Provides simple syntax via overloaded operators, including addition, retrieval, and removal of structures from anatomy:
anatomy = Anatomy() # target structure with label = 4 s1 = Structure(4, 'target', True) # non-target structure with label = 12 s2 = Structure(12, 'non-target', False) # non-target structure with label = 7 s3 = Structure(7, 'non-target 2', False) anatomy += s1 anatomy += s2 anatomy += s3 # remove structure s3 by name anatomy -= 'non-target 2' # remove structure s2 by label anatomy -= 12 # retrieve structure s1 by name anatomy[4] anatomy['target']
-
__iadd__
(other)[source]¶ Overload operator +=.
Append structure(s) in argument to
Anatomy
.Parameters: other – Singleton or iterable collection of Structure
objects.Returns: Updated anatomy. Return type: Anatomy
-
__isub__
(other)[source]¶ Overload operator -=.
Parameters: other – Name or label of structure to remove from Anatomy
.Returns: Downdated anatomy. Return type: Anatomy
-
calculate_doses
(beam_intensities)[source]¶ Calculate voxel doses to each structure in
Anatomy
.Parameters: beam_intensities – Beam intensities to provide to each structure’s Structure.calculate_dose method. Returns: None
-
clear_constraints
()[source]¶ Clear all constraints from all structures in
Anatomy
.Parameters: None – Returns: None
-
dose_summary_data
(percentiles=[2, 98])[source]¶ Collimate dose summaries from each structure in
Anatomy
.Parameters: percentiles ( list
) – List of percentiles to include in dose summary queries.Returns: Dictionary of dose summaries obtained by calling Structure.summary for each structure. Return type: dict
-
dose_summary_string
¶ Collimate dose summary strings from each structure in
Anatomy
.Parameters: None – Returns: Dictionary of dose summaries obtained by calling Structure.summary_string for each structure. Return type: dict
-
label_order
¶ Ranked list of labels of structures in
Anatomy
.Raises: ValueError
– If input to setter contains labels for structures not contained in anatomy, or if the length of the input list does not match Anatomy.n_structures.
-
plannable
¶ True
if all structures plannable and at least one is a target.
-
plotting_data
(constraints_only=False, maxlength=None)[source]¶ Dictionary of
matplotlib
-compatible plotting data for all structures.Parameters: - constraints_only (
bool
, optional) – IfTrue
, return only the constraints associated with each structure. - maxlength (
int
, optional) – If specified, re-sample each structure’s DVH plotting data to have a maximum series length ofmaxlength
.
- constraints_only (
-
propagate_doses
(voxel_doses)[source]¶ Assign pre-calculated voxel doses to each structure in
Anatomy
Parameters: voxel_doses ( dict
) – Dictionary mapping structure labels to voxel dose subvectors.Returns: None
-
structures
¶ Dictionary of structures in anatomy, keyed by label.
Setter method accepts any iterable collection of
Structure
objects.Raises: TypeError
– If input to setter is not iterable.ValueError
– If input to setter contains elements of a type other thanStructure
.
-
Define Structure
, building block of Anatomy
.
-
structure.
W_UNDER_DEFAULT
¶ float
Default objective weight for underdose penalty on target structures.
-
structure.
W_OVER_DEFAULT
¶ float
Default objective weight for underdose penalty on non-target structures.
-
structure.
W_NONTARG_DEFAULT
¶ float
Default objective weight for overdose penalty on non-target structures.
-
class
structure.
Structure
(label, name, is_target, size=None, **options)[source]¶ Structure
manages the dose information (including the dose influence matrix, dose calculations and dose volume histogram), as well as optimization objective information—including dose constraints—for a set of voxels (volume elements) in the patient volume to be treated as a logically homogeneous unit with respect to the optimization process.- There are usually three types of structures:
- Anatomical structures, such as a kidney or the spinal
cord, termed organs-at-risk (OARs),
- Clinically delineated structures, such as a tumor or a target
volume, and,
- Tissues grouped together by virtue of not being explicitly
delineated by a clinician, typically lumped together under the catch-all category “body”.
Healthy tissue structures, including OARs and “body”, are treated as non-target, are prescribed zero dose, and only subject to an overdose penalty during optimization.
Target tissue structures are prescribed a non-zero dose, and subject to both an underdose and an overdose penalty.
-
label
¶ (
int
orstr
): Label, applied to each voxel in the structure, usually generated during CT contouring step in the clinical workflow for treatment planning.
-
name
¶ str
Clinical or anatomical name.
-
is_target
¶ bool
True
if structure is a target.
-
dvh
¶ DVH
Dose volume histogram.
-
constraints
¶ ConstraintList
Mutable collection of dose constraints to be applied to structure during optimization.
-
A
¶ Alias for
Structure.A_full
.
-
A_full
¶ Full dose matrix (dimensions = voxels x beams).
- Setter method will perform two additional tasks:
- If
Structure.size
is not set, set it based on number of rows in
A_full
.
- If
- Trigger
Structure.A_mean
to be calculated from
- Trigger
Raises: TypeError
– IfA_full
is not a matrix innp.ndarray
,sp.csc_matrix
, orsp.csr_matrix
formats.ValueError
– IfStructure.size
is set, and the number of rows inA_full
does not matchStructure.size
.
-
A_mean
¶ Mean dose matrix (dimensions =
1
xbeams
).Setter expects a one dimensional
np.ndarray
representing the mean dose matrix for the structure. If this optional argument is not provided, the method will attempt to calculate the mean dose fromStructure.A_full
.Raises: TypeError
– IfA_mean
provided and not of typenp.ndarray
, or if mean dose matrix is to be calculated fromStructure.A_full
, but full dose matrix is not aconrad
-recognized matrix type.ValueError
– IfA_mean
is not dimensioned as a row or column vector, or number of beams implied byA_mean
conflicts with number of beams implied byStructure.A_full
.
-
assign_dose
(y)[source]¶ Assign dose vector to structure.
Parameters: y – Vector-like input of voxel doses. Returns: None Raises: ValueError
– if structure size is known and incompatible with length ofy
.
-
boost
¶ Adjustment factor from precription dose to optimization dose.
-
calc_y
(x)[source]¶ Calculate voxel doses as: attr:Structure.y =
Structure.A
*x
.Parameters: x – Vector-like input of beam intensities. Returns: None
-
calculate_dose
(beam_intensities)[source]¶ Alias for
Structure.calc_y()
.
-
collapsable
¶ True
if optimization can be performed with mean dose only.
-
constraints_string
¶ String of structure header and constraints
-
dose
¶ Dose level targeted in structure’s optimization objective.
The dose has two components: the precribed dose,
Structure.dose_rx
, and a multiplicative adjustment factor,Structure.boost
.Once the structure’s dose has been initialized, setting
Structure.dose
will change the adjustment factor. This is to distinguish (and allow for differences) between the dose level prescribed to a structure by a clinician and the dose level request to a numerical optimization algorithm that yields a desirable distribution, since the latter may require some offset relative to the former. To change the reference dose level, use theStructure.dose_rx
setter.Setter is no-op for non-target structures, since zero dose is prescribed always.
Raises: TypeError
– If requested dose does not have units ofDeliveredDose
.ValueError
– If zero dose is requested to a target structure.
-
dose_rx
¶ Prescribed dose level.
Setting this field sets
Structure.dose
to the requested value andStructure.boost
to1
.
-
dose_unit
¶ One times the
DeliveredDose
unit of the structure dose.
-
max_dose
¶ Maximum dose to structure’s voxels.
-
mean_dose
¶ Average dose to structure’s voxels.
-
min_dose
¶ Minimum dose to structure’s voxels.
-
objective_string
¶ String of structure header and objectives
-
plannable
¶ True if structure’s attached data is sufficient for optimization.
- Minimum requirements:
- Structure size determined, and
- Dose matrix assigned, or
- Structure collapsable and mean dose matrix assigned.
-
plotting_data
(constraints_only=False, maxlength=None)[source]¶ Dictionary of
matplotlib
-compatible plotting data.Data includes DVH curve, constraints, and prescribed dose.
Parameters: - constraints_only (
bool
, optional) – IfTrue
, return only the constraints associated with the structure. - maxlength (
int
, optional) – If specified, re-sample the structure’s DVH plotting data to have a maximum series length ofmaxlength
.
- constraints_only (
-
satisfies
(constraint)[source]¶ Test whether structure’s voxel doses satisfy
constraint
.Parameters: constraint (
Constraint
) – Dose constraint to test against structure’s voxel doses.Returns: True
if structure’s voxel doses conform to the queried constraint.Return type: bool
Raises: TypeError
– Ifconstraint
not of typeConstraint
.ValueError
– IfStructure.dvh
not initialized or not populated with dose data.
-
set_constraint
(constr_id, threshold=None, relop=None, dose=None)[source]¶ Modify threshold, relop, and dose of an existing constraint.
Parameters: - constr_id (
str
) – Key to a constraint inStructure.constraints
. - threshold (optional) – Percentile threshold to assign if
queried constraint is of type
PercentileConstraint
, no-op otherwise. Must be compatible with the setter method forPercentileConstraint.percentile
. - relop (optional) – Inequality constraint sense. Must be
compatible with the setter method for
Constraint.relop
. - dose (optional) – Constraint dose. Must be compatible with
setter method for
Constraint.dose
.
Returns: None
Raises: ValueError
– Ifconstr_id
is not the key to a constraint in theConstraintlist
located atStructure.constraints
.- constr_id (
-
size
¶ Structure size (i.e., number of voxels in structure).
Raises: ValueError
– Ifsize
not anint
.
-
summary
(percentiles=[2, 25, 75, 98])[source]¶ Dictionary summarizing dose statistics.
Parameters: percentiles ( list
, optional) – Percentile levels at which to query the structure dose. If not provided, will query doses at default percentile levels of 2%, 25%, 75% and 98%.Returns: Dictionary of doses at requested percentiles, plus mean, minimum and maximum voxel doses. Return type: dict
-
summary_string
¶ String of structure header and dose summary
-
voxel_weights
¶ Voxel weights, or relative volumes of voxels.
The voxel weights are the
1
vector if the structure volume is regularly discretized, and some other set of integer values if voxels are clustered.Raises: ValueError
– IfStructure.voxel_weights
setter called beforeStructure.size
is defined, or if length of input does not matchStructure.size
, or if any of the provided weights are negative.
-
y
¶ Vector of structure’s voxel doses.
-
y_mean
¶ Value of structure’s mean voxel dose.