Quickstart

Loading a plan

The easiest way to build a PatientPlan is to point from_folder() at a directory containing the patient’s DICOM files (CT series, RTSTRUCT, RTPLAN, RTDOSE physical dose, RTDOSE LET). It auto-discovers and cross-links the files via their DICOM reference tags:

from PyPlanAnalysis import PatientPlan

plan = PatientPlan.from_folder("path/to/patient_dicom_folder")

If your files aren’t in one flat, fully self-consistent folder, build the plan manually instead:

plan = PatientPlan(
    patient_id     = "Patient01",
    plan_file      = "RTPLAN.dcm",
    dose_file      = "RTDOSE_physical.dcm",
    let_file       = "RTDOSE_LET.dcm",
    rtstruct       = "RTSTRUCT.dcm",
    CT_folder_path = "CT/",
    n_fractions    = 30,
)

Running the analysis

results = plan.analyse(
    structures     = ["CTV", "Brainstem", "Parotid_L"],  # or None for all
    use_fractional = True,   # sub-voxel accurate masks (recommended)
    supersample    = 4,
)

analyse() accepts RBEConfig, MetricConfig, and RadiobiologyConfig to customise which RBE models, DVH/LVH metric points, and per-structure α/β / gEUD-a values are used. Sensible defaults are applied when omitted.

Exporting results

results.to_csv()          # <patient_id>/dvh_metrics.csv
results.to_excel()        # <patient_id>/dvh_metrics.xlsx
results.plot_dvh()        # <patient_id>/dvh_curves.pdf
results.plot_lvh()        # <patient_id>/lvh_curves.pdf
results.plot_dlvh()       # <patient_id>/dlvh_2d/*.png

# or all of the above at once:
results.save_all()

NTCP scoring

from PyPlanAnalysis import NTCPConfig

ntcp_cfg = NTCPConfig(models=["BrainNecrosis_5y", "HearingLoss_late"])
ntcp = results.CalcNTCP(ntcp_cfg)

path_models_xls may be omitted: it defaults to the parameter workbook bundled with the package. See NTCP Models Reference for the full list of available models.