pyanno4rt 0.22.0

A package for Python-based advanced numerical nonlinear optimization in radiotherapy.

Python-based Advanced Numerical Nonlinear Optimization for Radiotherapy

---

General information

pyanno4rt is a Python package for conventional and outcome prediction model-based inverse photon and proton treatment plan optimization, including radiobiological and machine learning (ML) models for tumor control probability (TCP) and normal tissue complication probability (NTCP). It leverages state-of-the-art local and global solution methods to handle both single- and multi-objective (un)constrained optimization problems, thereby covering a number of different problem designs. To summarize roughly, the following functionality is provided:

• Import of patient data and dose information from different sources
  
  • DICOM files (.dcm)
  • MATLAB files (.mat)
  • Python files (.npy, .p)


• Individual configuration and management of treatment plan instances
  
  • Dictionary-based plan generation
  • Dedicated logging channels and singleton datahubs
  • Automatic input checks to preserve the integrity
  • Snapshot/copycat functionality for storage and retrieval


• Multi-objective treatment plan optimization
  
  • Dose-fluence projections
    • Constant RBE projection
    • Dose projection
  • Fluence initialization strategies
    • Data medoid initialization
    • Tumor coverage initialization
    • Warm start initialization
  • Optimization methods
    • Lexicographic method
    • Weighted-sum method
    • Pareto analysis
  • 24-type dose-volume and outcome prediction model-based optimization component catalogue
  • Local and global solvers
    • Proximal algorithms provided by Proxmin
    • Multi-objective algorithms provided by Pymoo
    • Population-based algorithms provided by PyPop7
    • Local algorithms provided by SciPy


• Data-driven outcome prediction model handling
  
  • Dataset import and preprocessing
  • Automatic feature map generation
  • 27-type feature catalogue for iterative (re)calculation to support model integration into optimization
  • 7 customizable internal model classes (decision tree, k-nearest neighbors, logistic regression, naive Bayes, neural network, random forest, support vector machine)
    • Individual preprocessing, inspection and evaluation units
    • Adjustable hyperparameter tuning via sequential model-based optimization (SMBO) with robust k-fold cross-validation
    • Out-of-folds prediction for generalization assessment
  • External model loading via user-definable model folder paths


• Evaluation tools
  
  • Cumulative and differential dose volume histograms (DVH)
  • Dose statistics and clinical quality measures


• Graphical user interface
  
  • Responsive PyQt5 design with easy-to-use and clear surface
    • Treatment plan editor
    • Workflow controls
    • CT/Dose preview
  • Extendable visualization suite using Matplotlib and PyQt5
    • Optimization problem analysis
    • Data-driven model review
    • Treatment plan evaluation

Installation

Python distribution

You can install the latest distribution via:

pip install pyanno4rt

Source code

You can check the latest source code via:

git clone https://github.com/pyanno4rt/pyanno4rt.git

Usage

pyanno4rt has two main classes which provide a code-based and a UI-based interface:

Base class import for CLI/IDE

from pyanno4rt.base import TreatmentPlan

GUI import

from pyanno4rt.gui import GraphicalUserInterface

Dependencies

• python (>=3.10, <3.11)
• numpy (==1.26.4)
• proxmin (>=0.6.12)
• absl-py (>=2.1.0)
• pydicom (>=2.4.4)
• scikit-image (>=0.24.0)
• h5py (>=3.11.0)
• pandas (>=2.2.2)
• fuzzywuzzy (>=0.18.0)
• jax (>=0.4.30)
• jaxlib (>=0.4.30)
• numba (>=0.60.0)
• python-levenshtein (>=0.25.1)
• scikit-learn (>=1.5.1)
• tensorflow (==2.11.1)
• tensorflow-io-gcs-filesystem (==0.31.0)
• hyperopt (>=0.2.7)
• pymoo (>=0.6.1.1)
• pyqt5-qt5 (==5.15.2)
• pyqt5 (==5.15.10)
• pyqtgraph (>=0.13.7)
• ipython (>=8.26.0)
• matplotlib (==3.8.3)
• seaborn (>=0.13.2)
• pypop7 (>=0.0.80)

We are using Python version 3.10.14 with the Spyder IDE version 5.4.5 for development. For optimization, the package integrates external local and global solvers, where the L-BFGS-B algorithm from SciPy acts as default.

Development

Important links

• Official source code repo: https://github.com/pyanno4rt/pyanno4rt
• Download releases: https://pypi.org/project/pyanno4rt/
• Issue tracker: https://github.com/pyanno4rt/pyanno4rt/issues

Contributing

pyanno4rt is open for new contributors of all experience levels. Please get in contact with us (see "Help and support") to discuss the format of your contribution.

Note: the "docs" folder on Github includes example files with CT/segmentation data and the photon dose-influence matrix for the TG-119 case, a standard test phantom which can be used for development. You will find more realistic patient data e.g. in the CORT dataset¹ or the TROTS dataset².

_{¹D. Craft, M. Bangert, T. Long, et al. "Shared Data for Intensity Modulated Radiation Therapy (IMRT) Optimization Research: The CORT Dataset". GigaScience 3.1 (2014).
²S. Breedveld, B. Heijmen. "Data for TROTS - The Radiotherapy Optimisation Test Set". Data in Brief (2017).}

Help and support

Contact

• Mail: [e-mail]
• Github Discussions: https://github.com/pyanno4rt/pyanno4rt/discussions
• LinkedIn: https://www.linkedin.com/in/tim-ortkamp/

Citation

To cite this repository:

@misc{pyanno4rt2024,
  title = {{pyanno4rt}: python-based advanced numerical nonlinear optimization for radiotherapy},
  author = {Ortkamp, Tim and Jäkel, Oliver and Frank, Martin and Wahl, Niklas},
  year = {2024},
  howpublished = {\url{http://github.com/pyanno4rt/pyanno4rt}}
}