{"id":13654520,"url":"https://github.com/PortPy-Project/PortPy","last_synced_at":"2025-04-23T09:33:36.462Z","repository":{"id":65723293,"uuid":"531229335","full_name":"PortPy-Project/PortPy","owner":"PortPy-Project","description":"Opensource Python project for cancer radiation treatment planning [AAPM'23]","archived":false,"fork":false,"pushed_at":"2025-03-31T17:39:59.000Z","size":31162,"stargazers_count":139,"open_issues_count":0,"forks_count":26,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-12T12:55:05.757Z","etag":null,"topics":["artificial-intelligence","cancer","deep-learning","dicom","mathematical-modelling","medical-physics","optimization","python","pytorch","radiation-oncology","radiation-treatment-planning","radiotherapy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PortPy-Project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-08-31T19:27:49.000Z","updated_at":"2025-03-31T17:40:03.000Z","dependencies_parsed_at":"2024-11-16T03:27:08.087Z","dependency_job_id":"3eddbfb1-a35b-4f23-b8ea-6b202ee49e01","html_url":"https://github.com/PortPy-Project/PortPy","commit_stats":null,"previous_names":["portpy-project/portpy-photon"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PortPy-Project%2FPortPy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PortPy-Project%2FPortPy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PortPy-Project%2FPortPy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PortPy-Project%2FPortPy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PortPy-Project","download_url":"https://codeload.github.com/PortPy-Project/PortPy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250407714,"owners_count":21425549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","cancer","deep-learning","dicom","mathematical-modelling","medical-physics","optimization","python","pytorch","radiation-oncology","radiation-treatment-planning","radiotherapy"],"created_at":"2024-08-02T03:00:36.495Z","updated_at":"2025-04-23T09:33:31.444Z","avatar_url":"https://github.com/PortPy-Project.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/PortPy_logo.png\" width=\"40%\" height=\"40%\"\u003e\n\u003c/p\u003e\n\n![Version](https://img.shields.io/static/v1?label=latest\u0026message=v1.0.4.6\u0026color=darkgreen)\n[![Total Downloads](https://static.pepy.tech/personalized-badge/portpy?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=blue\u0026left_text=total%20downloads)](https://pepy.tech/project/portpy?\u0026left_text=totalusers)\n[![Monthly Downloads](https://static.pepy.tech/badge/portpy/month)](https://pepy.tech/project/portpy)\n# What is PortPy?\n\nPortPy, short for **P**lanning and **O**ptimization for **R**adiation **T**herapy, \nis an initiative aimed at creating an open-source Python library for \ncancer radiotherapy treatment planning optimization. \nThis project encompasses planning methodologies for Intensity Modulated Radiation Therapy (IMRT), \nVolumetric Modulated Arc Therapy (VMAT), and other emerging modalities. \nPortPy offers clinical-grade benchmark datasets and coding resources to promote *benchmarking*, \n*reproducibility*, and *community development*.\n\n\n**Note:** If you are new to the field, we suggest reviewing relevant literature review papers\n([Zarepisheh et al. 2021](https://pubsonline.informs.org/doi/abs/10.1287/inte.2021.1095), \n[Breedveld et al. 2019](https://www.sciencedirect.com/science/article/abs/pii/S0377221718307148), \n[Ehrgott et al. 2010](https://link.springer.com/article/10.1007/s10479-009-0659-4)) and watching YouTube videos \n([Edelman competition](https://www.youtube.com/watch?v=895M6j5KjPs\u0026t=1025s), \n[Varian IMRT](https://www.youtube.com/watch?v=eZS6DVGBx0k), \n[Elekta VMAT](https://www.youtube.com/watch?v=AE1SxvnFT3s)). In the near future, \nwe plan to launch an educational YouTube channel to assist researchers new to this field. \n  \n\n**Contents**\n- [Quick start and examples](#QuickStart)\n- [Benchmark data, benchmark algorithms, and PortPy toolkit](#benchmark)\n- [What can you do with PortPy?](#WhatDo)\n- [How to contribute?](#limitations)\n- [Data](#Data)\n- [Installation](#Installation)\n- [Team](#Team)\n\n# Quick start and examples \u003ca name=\"QuickStart\"\u003e\u003c/a\u003e\nThe easiest way to start is through the PorPy following examples. \n\n| Example File                          \t                                                                                                        | Description                                                                                                                                                           \t|\n|------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------\t|\n| [1_basic_tutorial.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb)                \t                | Demonstrates the main functionalities of PortPy (e.g., Access data, create an IMRT plan, visualize)                                                                   \t|\n| [vmat_scp_tutorial.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_tutorial.ipynb)               \t               | Creates a VMAT plan using sequential convex programming                                                                                                               \t|\n| [vmat_scp_dose_prediction.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_scp_dose_prediction.ipynb)                 | Predicts 3D dose distribution using deep learning and converts it into a deliverable VMAT plan                                                                        \t|\n| [3d_slicer_integration.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/3d_slicer_integration.ipynb)           \t           | Creates an IMRT plan and visualizes it in 3D-Slicer                                                                                                                   \t|\n| [imrt_tps_import.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_tps_import.ipynb)                \t                  | 1. Outputs IMRT plan in DICOM RT format and imports it into TPS. \u003cbr\u003e2. Outputs IMRT plan optimal fluence in an Eclipse-compatable format and imports it into Eclipse \t|\n| [vmat_tps_import.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_tps_import.ipynb)                 \t                 | Outputs VMAT plan in DICOM RT format and imports it into TPS                                                                                                          \t|\n| [imrt_dose_prediction.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_dose_prediction.ipynb)            \t            | Predicts 3D dose distribution using deep learning and converts it into a deliverable IMRT plan                                                                        \t|\n| [vmat_global_optimal.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/vmat_global_optimal.ipynb)           \t               | Finds a globally optimal VMAT plan                                                                                                                                    \t|\n| [beam_orientation_global_optimal.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/beam_orientation_global_optimal.ipynb) \t | Finds globally optimal beam angles for IMRT                                                                                                                           \t|\n| [dvh_constraint_global_optimal.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/dvh_constraint_global_optimal.ipynb)  \t    | Finds a globally optimal plan meeting Dose Volume Histogram (DVH) constraints                                                                                         \t|\n| [structure_operations.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/structure_operations.ipynb)            \t            | Creates new structures by expanding/shrinking the existing ones or using boolean operations                                                                           \t|\n| [inf_matrix_down_sampling.pynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/inf_matrix_down_sampling.ipynb)         \t        | Down-samples beamlets and/or voxels for computational efficiency                                                                                                      \t|\n| [inf_matrix_sparsification.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/inf_matrix_sparsification.ipynb)       \t       | Sparsifies (i.e., truncates) the influence matrix for computational efficiency                                                                                        \t|\n\n\n# Benchmark data, benchmark algorithms, and PortPy toolkit \u003ca name=\"benchmark\"\u003e\u003c/a\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./images/AI_Pyramid.png\" width=\"40%\" height=\"40%\"\u003e\n\u003cp\u003e\n\nThe figure above illustrates the inspiration behind developing PortPy, drawing from successful \nopen-source practices in the AI and computer science communities. Tools like PyTorch and TensorFlow, \nalong with benchmark datasets such as ImageNet and algorithms like AlexNet, have revolutionized AI \nand data science. Our goal is to replicate this success by providing researchers with a benchmark \ndataset (currently featuring 50 curated lung patients), benchmark algorithms for finding globally \noptimal plans using Mixed Integer Programming, and the PortPy toolkit for \ncreating, evaluating, and visualizing treatment plans.\n\n\n\n\n# What can you do with PortPy? \u003ca name=\"WhatDo\"\u003e\u003c/a\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./images/PortPy-Workflow.png\" width=\"90%\" height=\"40%\"\u003e\n\u003cp\u003e\n\nPortPy facilitates the **design**, **testing**, and **clinical validation** of new treatment planning algorithms. \nThis includes both cutting-edge AI-based models and traditional optimization techniques. \nThe above figure illustrates the PortPy design and its three main\nmodules: “Data Management”, “Plan Generation”, and “Plan\nEvaluation”,  which are discussed below. We recommend reviewing our Jupyter Notebooks \n[examples](#QuickStart) for a more comprehensive understanding of these modules. \n\n1. **Data Management**\n     * This module provides access to the curated benchmark PortPy dataset, allowing \n   researchers to test their algorithms on a standardized dataset (see [basic_tutorial.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb) notebook)\n     * The available data includes: \n        1) CT images and contours \n        2) all necessary data for optimization extracted from Eclipse using its API (version 16.1) \n        3) expert-selected beams for each patient \n        4) an IMRT plan for each patient, \ngenerated using our in-house automated planning system, \nECHO ([YouTube Video](https://youtu.be/895M6j5KjPs), [Paper](https://aapm.onlinelibrary.wiley.com/doi/epdf/10.1002/mp.13572)).\nMore information about data can be found in [Data](#Data) section.\n     * In the current version, you can only work with the benchmark dataset provided in this PortPy repo and \n   cannot use your own dataset for now. We will address this problem in the near future\n\n2. **Plan Generation**\n     * This module facilitates the generation of treatment plans using either classical optimization methods or \nemerging AI-based techniques \n     * For optimization tasks, PortPy has been integrated with [CVXPy](https://www.cvxpy.org/), a widely-used open-source package. \nCVXPy enables the high-level formulation of optimization problems and offers out-of-the-box access to a range\nof free (e.g., [SCIP](https://www.scipopt.org/), [SCIPY](https://docs.scipy.org/doc/scipy/reference/optimize.html)) and commercial (e.g., [MOSEK](https://www.mosek.com/), [CPLEX](https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer), [GUROBI](https://www.gurobi.com/)) optimization engines (available for free for research\npurposes) (see [basic_tutorial.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb) notebook)\n     * PortPy.AI module is equipped with essential functionalities for AI-based planning. These include data access, \ndata pre-processing, model training and testing, and patient-specific 3D dose prediction \n(see [imrt_dose_prediction.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_dose_prediction.ipynb) notebook)\n\n3. **Plan Visualization and Evaluation**\n     * Basic built-in visualization tools (e.g., DVH, dose distribution) are integrated into PortPy \n     * Enhanced visualizations are available through the integration with the popular open-source [3DSlicer](https://www.slicer.org/) package (see [3d_slicer_integration.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/3d_slicer_integration.ipynb) notebook)\n     * Plans can be quantitatively evaluated using well-established clinical protocols (e.g., Lung 2Gyx30, see  [basic_tutorial.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/1_basic_tutorial.ipynb))\n     * Plans can be imported into any TPS for final clinical evaluations  (see [imrt_tps_import.ipynb](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_tps_import.ipynb))  \n\n\n# How to contribute? \u003ca name=\"HowContribute\"\u003e\u003c/a\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./images/PortPy_Organization.png\" width=\"90%\" height=\"40%\"\u003e\n\u003cp\u003e\n\nAs illustrated in the above figure, PortPy organization includes \"PortPy\", which is the current repository, \nand PortPy extensions, which are the repositories developed using the PortPy as a platform. \nTo maintain the lightweight nature and user-friendliness of PortPy modules, our aim is to include only fundamental \nfunctionalities, along with benchmark data and algorithms in the PortPy repo, and establish separate repositories \nfor other projects, similar to what we've done for projects like [LowDimRT](https://github.com/PortPy-Project/LowDimRT)\nand [ECHO VMAT](https://github.com/PortPy-Project/ECHO-VMAT).\n\nIf you're interested in contributing to existing PortPy modules or wish to create a new module, \nwe encourage you to contact us first. This will help ensure that our objectives and priorities are aligned. \nIf you use PortPy to build your own package, you're welcome to host your package within the\n[PortPy-Project orgainization](https://github.com/PortPy-Project). \nAlternatively, you can host your package on your own GitHub page. In this case, \nplease inform us so that we can fork it and feature it under the PortPy-Project organization. \nFor those keen on creating a logo for their repository, we offer the option to customize our [pre-designed logo](https://www.canva.com/design/DAFxivHC0Js/YqZREdr26pmEsIgCeuU-iA/view?utm_content=DAFxivHC0Js\u0026utm_campaign=designshare\u0026utm_medium=link\u0026utm_source=publishsharelink\u0026mode=preview).\n\n\n# Data \u003ca name=\"Data\"\u003e\u003c/a\u003e\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"./images/PortPy Data.png\" width=\"90%\" height=\"40%\"\u003e\n\u003cp\u003e\nPortPy equips researchers with a robust benchmark patient dataset, sourced from the FDA-approved Eclipse commercial treatment planning system through its API. This dataset embodies all necessary elements for optimizing various machine configurations such as beam angles, aperture shapes, and leaf movements. It includes\n\n1. **Dose Influence Matrix (AKA dose deposition matrix, dij matrix):** The dose contribution of each beamlet to each voxel,\n2. **Beamlets/Voxels Details:** Detailed information about the position and size of beamlets/voxels,\n3. **Expert-Selected Benchmark Beams:** An expert clinical physicist has carefully selected benchmark beams, providing reference beams for comparison and benchmarking,\n4. **Benchmark IMRT Plan:** A benchmark IMRT plan generated using our in-house automated treatment planning system called ECHO ([YouTube Video](https://youtu.be/895M6j5KjPs), [Paper](https://aapm.onlinelibrary.wiley.com/doi/epdf/10.1002/mp.13572)). This plan serves as a benchmark for evaluating new treatment planning algorithms.\n5. **Benchmark Clinical Criteria:** A set of clinically relevant mean/max/DVH criteria for plan evaluation. \nCurrently, this set encompasses only the Lung 2Gy×30 protocol but will be expanded in the future to more protocols as well as TCP/NTCP evaluation functions.  \n\nTo access these resources, users are advised to download the latest version of the dataset, \nwhich can be found [here](https://drive.google.com/drive/folders/1nA1oHEhlmh2Hk8an9e0Oi0ye6LRPREit?usp=sharing). \nSubsequently, create a directory titled './data' in the current project directory and transfer the downloaded \nfile into it. For example, ./data/Lung_Phantom_Patient_1. \nWe have adopted the widely-used JSON and HDF5 formats for data storage.\n[HDFViwer](https://www.hdfgroup.org/downloads/hdfview/) can be utilized to view the contents of the HDF5 files.  \n\n\n\n**Note:** Initially, we will utilize a lung dataset from [TCIA](https://wiki.cancerimagingarchive.net/display/Public/NSCLC-Radiomics). The original DICOM CT images and structure sets are not included in the PortPy dataset and need to be directly downloaded from the TCIA. Users can fetch the **TCIA collection ID** and the **TCIA subject ID** for each PortPy patient using the *get_tcia_metadata()* method in PortPy and subsequently download the data from TCIA (see [imrt_tps_import](https://github.com/PortPy-Project/PortPy/blob/master/examples/imrt_tps_import.ipynb))\n\n\n# Installation \u003ca name=\"Installation\"\u003e\u003c/a\u003e\n\n1. Install using pip:\n   \n    * Run the command '**pip install portpy**'\n    * You can install optional packages using '**pip install portpy[mosek, pydicom]**'.\n   \n\n2. Install using conda:\n\n    * Run the command '**conda install -c conda-forge portpy**'\n\n3. Install from source:\n   \n    * Clone this repository using '**git clone https://github.com/PortPy-Project/PortPy.git**'\n    * Navigate to the repository with '**cd portpy**'\n\n    * Install the dependencies within a Python virtual environment or Anaconda environment. To set up in a Python virtual environment, install all the dependencies specified in requirements.txt as follows:\n        * Create the virtual environment with '**python3 -m venv venv**'\n        * Activate the environment with '**source venv/bin/activate**'\n        * Install the requirements using '**(venv) pip install -r requirements.txt**'\n\n\n# Team \u003ca name=\"Team\"\u003e\u003c/a\u003e\nPortPy is a community project initiated at [Memorial Sloan Kettering Cancer Center](https://www.mskcc.org/). It is currently developed and maintained by:\n\n| Name                                                                         | Expertise                                        | Institution                            |\n|------------------------------------------------------------------------------|--------------------------------------------------|----------------------------------------|\n| [Masoud Zarepisheh](https://masoudzp.github.io/)                             | Treatment Planning and Optimization              | Memorial Sloan Kettering Cancer Center |\n| [Saad Nadeem](https://nadeemlab.org/)                                        | Computer Vision and AI in Medical Imaging        | Memorial Sloan Kettering Cancer Center |\n| [Gourav Jhanwar](https://github.com/gourav3017)                              | Algorithm Design and Development                 | Memorial Sloan Kettering Cancer Center |\n| [Mojtaba Tefagh](https://www.ed.ac.uk/profile/mojtaba-tefagh)                | Mathematical Modeling and Reinforcement Learning | University of Edinburgh, Scotland      |\n| [Vicki Taasti](https://scholar.google.com/citations?user=PEPyvewAAAAJ\u0026hl=en) | Physics and Planning of Proton Therapy           | Aarhus University, Denmak              |\n| [Seppo Tuomaala](https://www.linkedin.com/in/seppo-tuomaala-5b57913/)        | Eclispe API Scripting                            | Varian Medical Systems                 |\n\n# License \u003ca name=\"License\"\u003e\u003c/a\u003e\nPortPy code is distributed under **Apache 2.0 with Commons Clause** license, and is available for non-commercial academic purposes.\n\n# Reference \u003ca name=\"Reference\"\u003e\u003c/a\u003e\nIf you find our work useful in your research or if you use parts of this code please cite our [AAPM'23 abstract](https://aapm.confex.com/aapm/2023am/meetingapp.cgi/Paper/4208) :\n```\n@article{jhanwar2023portpy,\n  title={Portpy: An Open-Source Python Package for Planning and Optimization in Radiation Therapy Including Benchmark Data and Algorithms},\n  author={Jhanwar, Gourav and Tefagh, Mojtaba and Taasti, Vicki T and Alam, Sadegh R and Tuomaala, Seppo and Nadeem, Saad and Zarepisheh, Masoud},\n  journal={AAPM 65th Annual Meeting \u0026 Exhibition},\n  year={2023}\n}\n```\n\n\n\u003e Written with [StackEdit](https://stackedit.io/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPortPy-Project%2FPortPy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPortPy-Project%2FPortPy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPortPy-Project%2FPortPy/lists"}