Case

Define Case, the top level interface for treatment planning.

class case.Case(anatomy=None, physics=None, prescription=None, suppress_rx_constraints=False)

Top level interface for treatment planning.

A Case has four major components.

Case.physics is of type Physics, 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 type Antomy, and manages the structures in the patient anatomy, including optimization objectives and dose constraints applied to each structure.

Case.prescription is of type Prescription, 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 type PlanningProblem, 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)

Add constraint to structure specified by structure_label.

Parameters:

• structure_label – Must correspond to label or name of a Structure in Case.anatomy.
• constraint (conrad.medicine.Constraint) – Dose constraint to add to constraint list of specified structure.

Returns:

None

anatomy

Container for all planning structures.

anatomy_for_frame(frame_name)

calculate_doses(x)

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)

Modify constraint in Case.

If constr_id is a valid key to a constraint in the ConstraintList attached to one of the structures in Case.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

change_objective(label, **objective_parameters)

Modify objective for structure in Case.

Parameters:

• label – Label or name of a Structure in Case.anatomy.
• **options –

Returns:

None

clear_constraints()

Remove all constraints from all structures in Case.

Parameters:None – Returns:None

drop_constraint(constr_id)

Remove constraint from case.

If constr_id is a valid key to a constraint in the ConstraintList attached to one of the structures in Case.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()

Gather dose matrices from structures.

Parameters:None – Returns:None Raises:AttributeError – If case.physics.dose_matrix is already set.

load_physics_to_anatomy(overwrite=False, frame='active')

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 from Case.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) – If True, dose matrix data from Case.physics will overwrite dose matrices assigned to each structure in Case.anatomy. Returns:None Raises:ValueError – If Case.anatomy has assigned dose matrices, Case.physics not marked as having updated dose matrix data, and flag overwrite set to False.

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)

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 to Case.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 a RunRecord 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.

plannable

True if case meets minimum requirements for Case.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)

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

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 when Case.prescription setter is invoked.

problem

Object managing numerical optimization setup and results.

propagate_doses(y)

Split voxel dose vector y into doses for each structure in Case.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()

Push constraints in prescription onto structures in anatomy.

Assume each structure label represented in Case.prescription is represented in Case.anatomy. Any existing constraints on structures in Case.anatomy are preserved.

Parameters:None – Returns:None