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']

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`

is_empty¶: True if Anatomy contains no structures.

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.

labels¶: List of labels of structures in Anatomy.

list¶: List of structures in Anatomy.

n_structures¶: Number of structures in Anatomy.

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) – If `True`, 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 of `maxlength`.

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

satisfies_prescription(constraint_dict)[source]¶

Check whether anatomy satisfies supplied constraints.

:param dict: Dictionary of ConstraintList objects :param keyed by structure labels.:

Returns:	True if each structure in
Return type:	`int`

size¶: Total number of voxels in all structures in Anatomy.

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 than `Structure`.

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 or str): 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.
Trigger Structure.A_mean to be calculated from

Structure.A_full.

Raises:	`TypeError` – If `A_full` is not a matrix in `np.ndarray`, `sp.csc_matrix`, or `sp.csr_matrix` formats. `ValueError` – If `Structure.size` is set, and the number of rows in `A_full` does not match `Structure.size`.

A_mean¶

Mean dose matrix (dimensions = 1 x beams).

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 from Structure.A_full.

Raises:	`TypeError` – If `A_mean` provided and not of type `np.ndarray`, or if mean dose matrix is to be calculated from `Structure.A_full`, but full dose matrix is not a `conrad`-recognized matrix type. `ValueError` – If `A_mean` is not dimensioned as a row or column vector, or number of beams implied by `A_mean` conflicts with number of beams implied by `Structure.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 of `y`.

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 the Structure.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 of `DeliveredDose`. `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 and Structure.boost to 1.

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) – If `True`, 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 of `maxlength`.

reset_matrices()[source]¶: Reset structure’s dose and mean dose matrices to None

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` – If `constraint` not of type `Constraint`. `ValueError` – If `Structure.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 in `Structure.constraints`. threshold (optional) – Percentile threshold to assign if queried constraint is of type `PercentileConstraint`, no-op otherwise. Must be compatible with the setter method for `PercentileConstraint.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` – If `constr_id` is not the key to a constraint in the `Constraintlist` located at `Structure.constraints`.

size¶

Structure size (i.e., number of voxels in structure).

Raises:	`ValueError` – If `size` not an `int`.

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` – If `Structure.voxel_weights` setter called before `Structure.size` is defined, or if length of input does not match `Structure.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.