Case¶
Define Case
, the top level interface for treatment planning.
-
class
case.
Case
(anatomy=None, physics=None, prescription=None, suppress_rx_constraints=False)[source]¶ Top level interface for treatment planning.
A
Case
has four major components.Case.physics
is of typePhysics
, and contains physical information for the case, including the number of voxels, beams, beam layout, voxel labels and dose influence matrix.Case.anatomy
is of typeAntomy
, and manages the structures in the patient anatomy, including optimization objectives and dose constraints applied to each structure.Case.prescription
is of typePrescription
, and specifies a clinical prescription for the case, including prescribed doses for target structures and prescribed dose constraints (e.g., RTOG recommendations).Case.problem
is of typePlanningProblem
, and is a tool that forms and manages the mathematical representation of treatment planning problem specified by case anatomy, physics and prescription; it serves as the interface to convex solvers that run the treatment plan optimization.-
A
¶ Dose matrix from current planning frame of
Case.physics
.
-
add_constraint
(structure_label, constraint)[source]¶ Add
constraint
to structure specified bystructure_label
.Parameters: - structure_label – Must correspond to label or name of a
Structure
inCase.anatomy
. - constraint (
conrad.medicine.Constraint
) – Dose constraint to add to constraint list of specified structure.
Returns: None
- structure_label – Must correspond to label or name of a
-
anatomy
¶ Container for all planning structures.
-
calculate_doses
(x)[source]¶ Calculate voxel doses for each structure in
Case.anatomy
.Parameters: x – Vector-like np.array of beam intensities. Returns: None
-
change_constraint
(constr_id, threshold=None, direction=None, dose=None)[source]¶ Modify constraint in
Case
.If
constr_id
is a valid key to a constraint in theConstraintList
attached to one of the structures inCase.anatomy
, that constraint will be modified according to the remaining arguments. Call is no-op if key does not exist.Parameters: - constr_id – Key to a constraint on one of the structures in
Case.anatomy
. - threshold (optional) – If constraint in question is a
PercentileConstraint
, percentile threshold set to this value. No effect otherwise. - direction (
str
, optional) – Constraint direction set to this value. Should be one of: ‘<’ or ‘>’. - dose (
DeliveredDose
, optional) – Constraint dose level set to this value.
Returns: None
- constr_id – Key to a constraint on one of the structures in
-
change_objective
(label, **objective_parameters)[source]¶ Modify objective for structure in
Case
.Parameters: - label – Label or name of a
Structure
inCase.anatomy
. - **options –
Returns: None
- label – Label or name of a
-
clear_constraints
()[source]¶ Remove all constraints from all structures in
Case
.Parameters: None – Returns: None
-
drop_constraint
(constr_id)[source]¶ Remove constraint from case.
If
constr_id
is a valid key to a constraint in theConstraintList
attached to one of the structures inCase.anatomy
, that constraint will be removed from the structure’s constraint list. Call is no-op if key does not exist.Parameters: constr_id – Key to a constraint on one of the structures in Case.anatomy
.Returns: None
-
gather_physics_from_anatomy
()[source]¶ Gather dose matrices from structures.
Parameters: None – Returns: None Raises: AttributeError
– Ifcase.physics.dose_matrix
is already set.
-
load_physics_to_anatomy
(overwrite=False)[source]¶ Transfer data from physics to each structure.
The label associated with each structure in
Case.anatomy
is used to retrieve the dose matrix data and voxel weights fromCase.physics
for the voxels bearing that label.The method marks the
Case.physics.dose_matrix
as seen, in order to prevent redundant data transfers.Parameters: overwrite ( bool
, optional) – IfTrue
, dose matrix data fromCase.physics
will overwrite dose matrices assigned to each structure inCase.anatomy
.Returns: None Raises: ValueError
– IfCase.anatomy
has assigned dose matrices,Case.physics
not marked as having updated dose matrix data, and flagoverwrite
set toFalse
.
-
n_beams
¶ Number of beams in current planning frame of
Case.physics
.
-
n_structures
¶ Number of structures in
Case.anatomy
.
-
n_voxels
¶ Number of voxels in current planning frame of
Case.physics
.
-
physics
¶ Patient anatomy, contains all dose physics information.
-
plan
(use_slack=True, use_2pass=False, **options)[source]¶ Invoke numerical solver to optimize plan, given state of
Case
.At call time, the objectives, dose constraints, dose matrix, and other relevant data associated with each structure in
Case.anatomy
is passed toCase.problem
to build and solve a convex optimization problem.Parameters: - use_slack (
bool
, optional) – Allow slacks on each dose constraint. - use_2pass (
bool
, optional) – Execute two-pass planing method to enforce exact versions, rather than convex restrictions of any percentile-type dose constraints included in the plan. - **options – Arbitrary keyword arguments. Passed through to
Case.problem.solve()
.
Returns: Tuple with
bool
indicator of planning problem feasibility and aRunRecord
with data from the setup, execution and output of the planning run.Return type: tuple
Raises: ValueError
– If case not plannable due to missing information.- use_slack (
-
plannable
¶ True
if case meets minimum requirements forCase.plan()
call.Parameters: None – Returns: True
if anatomy has one or more target structures and dose matrices from the case physics.Return type: bool
-
plotting_data
(x=None, constraints_only=False, maxlength=None)[source]¶ Dictionary of
matplotlib
-compatible plotting data.Includes data for dose volume histograms, prescribed doses, and dose volume (percentile) constraints for each structure in
Case.anatomy
.Parameters: - x (optional) – Vector of beam intensities from which to calculate structure doses prior to emitting plotting data.
- constraints_only (
bool
, optional) – IfTrue
, only include each structure’s constraint data in returned dictionary. - maxlength (
int
, optional) – If specified, re-sample each structure’s DVH plotting data to have a maximum series length ofmaxlength
.
Returns: Plotting data for each structure, keyed by structure label.
Return type: dict
-
prescription
¶ Container for clinical goals and limits.
Structure list from prescription used to populate
Case.anatomy
if anatomy is empty whenCase.prescription
setter is invoked.
-
problem
¶ Object managing numerical optimization setup and results.
-
propagate_doses
(y)[source]¶ Split voxel dose vector
y
into doses for each structure inCase.anatomy
.Parameters: y – Vector-like np.array of voxel doses, or dictionary mapping structure labels to voxel dose subvectors,
-
structures
¶ Dictionary of structures contained in
Case.anatomy
.
-
transfer_rx_constraints_to_anatomy
()[source]¶ Push constraints in prescription onto structures in anatomy.
Assume each structure label represented in
Case.prescription
is represented inCase.anatomy
. Any existing constraints on structures inCase.anatomy
are preserved.Parameters: None – Returns: None
-