pyanno4rt.base

Base module.

This module aims to provide base classes to generate treatment plans.

Overview

Classes

TreatmentPlan

Base treatment plan class.

Classes

class pyanno4rt.base.TreatmentPlan(configuration, optimization, evaluation=None)[source]

Base treatment plan class.

This class enables configuration, optimization, evaluation, and visualization of individual IMRT treatment plans. It therefore provides a simple, but extensive interface using input dictionaries for the different parameter groups.

Parameters:

  • configuration (dict) –

    Dictionary with the treatment plan configuration parameters.

    • labelstr

      Unique identifier for the treatment plan.

      Note

      Uniqueness of the label is important because it prevents overwriting processes between different treatment plan instances by isolating their datahubs, logging channels and general storage paths.

    • min_log_level{‘debug’, ‘info’, ‘warning’, ‘error, ‘critical’}, default=’info’

      Minimum logging level.

    • modality{‘photon’, ‘proton’}

      Treatment modality, needs to be consistent with the dose calculation inputs.

      Note

      If the modality is ‘photon’, DoseProjection with neutral RBE of 1.0 is automatically applied, whereas for the modality ‘proton’, ConstantRBEProjection with constant RBE of 1.1 is used.

    • number_of_fractionsint

      Number of fractions according to the treatment scheme.

    • imaging_pathstr

      Path to the CT and segmentation data.

      Note

      It is assumed that CT and segmentation data are included in a single file (.mat or .p) or a series of files (.dcm), whose content follows the pyanno4rt data structure.

    • target_imaging_resolutionNone or list, default=None

      Imaging resolution for post-processing interpolation of the CT and segmentation data, only used if a list is passed.

    • dose_matrix_pathstr

      Path to the dose-influence matrix file (.mat or .npy).

    • dose_resolutionlist

      Size of the dose grid in [mm] per dimension, needs to be consistent with the dose calculation inputs.

  • optimization (dict) –

    Dictionary with the treatment plan optimization parameters.

    • componentsdict

      Optimization components for each segment of interest, i.e., objective functions and constraints.

      Note

      The declaration scheme for a single component is

      {<segment>: {‘type’: <1>, ‘instance’: {‘class’: <2>, ‘parameters’: <3>}

      • <1>: ‘objective’ or ‘constraint’

      • <2>: component label (see note below)

      • <3> parameter dictionary for the component (see the component classes for details)

      Multiple objectives and/or constraints can be assigned by passing a list of dictionaries for each segment of interest.

      The following components are currently available:

    • method{‘lexicographic’, ‘pareto’, ‘weighted-sum’}, default=’weighted-sum’

      Single- or multi-criteria optimization method, see the classes LexicographicOptimization ParetoOptimization WeightedSumOptimization.

      • ’lexicographic’ : sequential optimization based on a preference order

      • ’pareto’ : parallel optimization based on the criterion of pareto optimality

      • ’weighted-sum’ : parallel optimization based on a weighted-sum scalarization of the objective function

    • solver{‘proxmin’, ‘pymoo’, ‘pypop7’, ‘scipy’}, default=’scipy’

      Python package to be used for solving the optimization problem, see the classes ProxminSolver PymooSolver PyPop7Solver SciPySolver.

      • ’proxmin’ : proximal algorithms provided by Proxmin

      • ’pymoo’ : multi-objective algorithms provided by Pymoo

      • ’pypop7’: population-based algorithms provided by PyPop7

      • ’scipy’ : local algorithms provided by SciPy

      Note

      The ‘lexicographic’ method currently only works with ‘scipy’, while the ‘pareto’ method only works with ‘pymoo’.

    • algorithmstr

      Solution algorithm from the chosen solver:

      • solver=’proxmin’ : {‘admm’, ‘pgm’, ‘sdmm’}, default=’pgm’

        • ’admm’ : alternating direction method of multipliers

        • ’pgm’ : proximal gradient method

        • ’sdmm’ : simultaneous direction method of multipliers

      • solver=’pymoo’ : {‘NSGA3’}, default=’NSGA3’

        • ’NSGA3’ : non-dominated sorting genetic algorithm III

      • solver=’pypop7’ : {‘LMCMA’, ‘LMMAES’}, default=’LMCMA’

        • ’LMCMA’ : limited-memory covariance matrix adaptation

        • ’LMMAES’ : limited-memory matrix adaptation evolution strategy

      • solver=’scipy’ : {‘L-BFGS-B’, ‘TNC’, ‘trust-constr’}, default=’L-BFGS-B’

        • ’L-BFGS-B’ : bounded limited memory Broyden-Fletcher-Goldfarb-Shanno method

        • ’TNC’ : truncated Newton method

        • ’trust-constr’ : trust-region constrained method

      Note

      Constraints are currently only supported by ‘NSGA3’ and ‘trust-constr’.

    • initial_strategy{‘data-medoid’, ‘target-coverage’, ‘warm-start’}, default=’target-coverage’

      Initialization strategy for the fluence vector (see the class FluenceInitializer).

      • ’data-medoid’ : fluence vector initialization with respect to data medoid points

      • ’target-coverage’ : fluence vector initialization with respect to tumor coverage

      • ’warm-start’ : fluence vector initialization with respect to a reference optimal point

      Note

      Data-medoid initialization works best for a single dataset or multiple datasets with a high degree of similarity. Otherwise, the initial fluence vector may lose its individual representativeness.

    • initial_fluence_vectorNone or list, default=None

      User-defined initial fluence vector for the optimization problem, only used if initial_strategy=’warm-start’ (see the class FluenceInitializer).

    • lower_variable_boundsNone, int, float, or list, default=0

      Lower bound(s) on the decision variables.

    • upper_variable_boundsNone, int, float, or list, default=None

      Upper bound(s) on the decision variables.

    Note

    There are two options to set lower and upper bounds for the variables:

    1. Passing a single numeric value translates into uniform bounds across all variables (where None for the lower and/or upper bound indicates infinity bounds)

    2. Passing a list translates into non-uniform bounds (here, the length of the list needs to be equal to the number of decision variables)

    • max_iterint, default=500

      Maximum number of iterations taken for the solver to converge.

    • tolerancefloat, default=1e-3

      Precision goal for the objective function value.

  • evaluation (None or dict, default=None) –

    Dictionary with the treatment plan evaluation parameters.

    • dvh_type{‘cumulative’, ‘differential’}, default=cumulative’

      Type of DVH to be evaluated.

    • number_of_pointsint, default=1000

      Number of (evenly-spaced) points for which to evaluate the DVH.

    • reference_volumelist, default=[2, 5, 50, 95, 98]

      Reference volumes for which to evaluate the inverse DVH values.

    • reference_doselist, default=[]

      Reference dose values for which to evaluate the DVH values.

      Note

      If the default value is used, reference dose levels will be determined automatically.

    • display_segmentslist, default=[]

      Names of the segmented structures to be displayed.

      Note

      If the default value is used, all segments will be displayed.

    • display_metricslist, default=[]

      Names of the plan evaluation metrics to be displayed.

      Note

      If the default value is used, all metrics will be displayed.

      The following metrics are currently available:

      • ’mean’: mean dose

      • ’std’: standard deviation of the dose

      • ’max’: maximum dose

      • ’min’: minimum dose

      • ’Dx’: dose quantile(s) for level x (reference_volume)

      • ’Vx’: volume quantile(s) for level x (reference_dose)

      • ’CI’: conformity index

      • ’HI’: homogeneity index

configuration

See ‘Parameters’.

Type:

dict

optimization

See ‘Parameters’.

Type:

dict

evaluation

See ‘Parameters’.

Type:

dict

input_checker

The object used to approve the input dictionaries.

Type:

object of class InputChecker

logger

The internal object used to print and store logging messages.

Type:

None or object of class Logger

datahub

The object used to manage and distribute information units.

Type:

None or object of class Datahub

patient_loader

The object used to import and type-convert CT and segmentation data.

Type:

None or object of class PatientLoader

plan_generator

The object used to set and type-convert plan properties.

Type:

None or object of class PlanGenerator

dose_info_generator

The object used to specify and type-convert dose (grid) properties.

Type:

None or object of class DoseInfoGenerator

fluence_optimizer

The object used to solve the fluence optimization problem.

Type:

None or object of class FluenceOptimizer

dose_histogram

The object used to evaluate the dose-volume histogram (DVH).

Type:

None or object of class DVHEvaluator

dosimetrics

The object used to evaluate the dosimetrics.

Type:

None or object of class DosimetricsEvaluator

visualizer

The object used to visualize the treatment plan.

Type:

None or object of class Visualizer

Example

Our Read the Docs page (https://pyanno4rt.readthedocs.io/en/latest/) features a step-by-step example for the application of this class. You will also find code templates there, e.g. for the optimization components.

Overview

Methods

configure()

Initialize the configuration classes and process the input data.

optimize()

Initialize the fluence optimizer and solve the problem.

evaluate()

Initialize the evaluation classes and compute the plan metrics.

visualize(parent)

Initialize the visualization interface and launch it.

compose()

Compose the treatment plan by cycling the entire workflow.

update(key_value_pairs)

Update the input dictionaries by specific key-value pairs.

Members

configure()[source]

Initialize the configuration classes and process the input data.

optimize()[source]

Initialize the fluence optimizer and solve the problem.

Raises:

AttributeError – If the treatment plan has not been configured yet.

evaluate()[source]

Initialize the evaluation classes and compute the plan metrics.

Raises:

AttributeError – If the treatment plan has not been optimized yet.

visualize(parent=None)[source]

Initialize the visualization interface and launch it.

Parameters:

parent (None or object of class MainWindow, default=None) – The object used as a parent window for the visualization interface.

Raises:

AttributeError – If the treatment plan has not been optimized (and evaluated) yet.

compose()[source]

Compose the treatment plan by cycling the entire workflow.

update(key_value_pairs)[source]

Update the input dictionaries by specific key-value pairs.

Parameters:

key_value_pairs (dict) – Dictionary with the keys and values to update.

Raises:

KeyError – If any update key is not included in the parameter dictionaries.