PyPlanAnalysis.plan

Main user-facing API: PatientPlan loads DICOM data and runs the analysis; AnalysisResults holds the metrics, plots, and NTCP outputs and exports them.

PyPlanAnalysis.plan

Main user-facing API: PatientPlan (loads DICOM data and runs the analysis) and AnalysisResults (metrics, plots, NTCP, and exports). See the project README for usage examples.

class PatientPlan(patient_id=None, plan_file=None, dose_file=None, let_file=None, rtstruct=None, CT_folder_path=None, n_fractions=None)

Bases: object

Represents a single patient’s proton therapy plan.

Parameters:

• patient_id (str) – Identifier used in output filenames and CSV column.

• dose_file (str or Path) – DICOM RT Dose file containing physical dose [Gy].

• let_file (str or Path) – DICOM RT Dose file containing LETd [keV/µm] stored as dose grid.

• rtstruct (str or Path) – DICOM RT Struct file.

• CT (str or Path) – folder of DICOM CT files

• method (Class)

• ------------

• PatientPlan.from_folder(folder – Auto-discover DICOM files from a folder.

• patient_id=None) – Auto-discover DICOM files from a folder.

• plan_file (str | Path | None)

• CT_folder_path (str | Path | None)

• n_fractions (int | None)

classmethod from_folder(folder, n_fractions=None)

Create a PatientPlan by auto-discovering DICOM files in folder.

Parameters:

• folder (path containing .dcm files)

• patient_id (if None, uses the folder name)

• n_fractions (int | None)

Return type:

PatientPlan

load()

Load and cache all DICOM data. Called automatically by analyse().

property structure_names: list

List of all structure names in the RT Struct.

property voxel_volume_cc: float

Volume of one dose voxel in cc.

analyse(structures=None, rbe_cfg=None, metric_cfg=None, radiobio_cfg=None, resample_on_CT=False, resample_on_custom_grid=False, use_fractional=False, supersample=4)

Run the full analysis pipeline for this patient.

Parameters:

• structures (list of structure name strings, or None (= all))

• rbe_cfg (RBEConfig (default: all three models, RBE=1.1))

• metric_cfg (MetricConfig (default values))

• radiobio_cfg (RadiobiologyConfig (default per-tissue α/β and gEUD-a))

• resample (if True, interpolate dose values to the new spacing defined in MetricConfig)

• use_fractional (if True, use fractional voxel membership mask instead) – of binary mask. More accurate for small structures. Each voxel is weighted by the fraction of its volume inside the contour. Default: False.

• supersample (supersampling factor for fractional mask (N×N sub-points) – per voxel). Only used when use_fractional=True. Default: 4 (16 sub-points per voxel, ~6% accuracy).

• resample_on_CT (bool)

• resample_on_custom_grid (bool)

Return type:

AnalysisResults

Returns:

AnalysisResults

class AnalysisResults(patient_id, metrics_df, dvh_data, lvh_data, dlvh_data_diff, dlvh_data_cum)

Bases: object

Container for all outputs from PatientPlan.analyse().

Parameters:

• patient_id (str)

• metrics_df (DataFrame)

• dvh_data (dict)

• lvh_data (dict)

• dlvh_data_diff (dict)

• dlvh_data_cum (dict)

patient_id

Type:

str

metrics_df

Type:

pd.DataFrame – all DVH/LVH metrics, one row per structure

dvh_data

Type:

dict {struct: {dose_type: (edges, cum)}} e.g. # {“CTV”: {“Physical”: (edges, cum), “RBE×1.1”: (edges, cum), …}, “Brainstem”: {“Physical”: (edges, cum), …},

lvh_data

Type:

dict {struct: (edges, cum)}

dlvh_data

Type:

dict {struct: (H, dose_edges, let_edges)}

CalcNTCP(NTCPConfig, path_models_xls=None)

Parameters:

• NTCPConfig (NTCPConfig)

• path_models_xls (str)

to_csv(path=None)

Save metrics to CSV.

Parameters:

path (output path. Default: "<patient_id>/dvh_metrics.csv")

Return type:

Path

to_excel(path=None)

Save metrics to Excel (.xlsx).

Parameters:

path (output path. Default: "<patient_id>/dvh_metrics.xlsx")

Return type:

Path

plot_dvh(save=None, dpi=350)

Generate DVH curve figures.

Creates one figure per dose type (Physical, RBE×1.1, each model) showing all structures, PLUS one per-structure comparison figure.

Parameters:

• save (path for output PDF. Default: "<patient_id>/dvh_curves.pdf")

• dpi (figure DPI)

Return type:

list

Returns:

list of matplotlib Figures

plot_lvh(save=None, dpi=150)

Generate LVH curve figure (all structures on one plot).

Parameters:

• save (path for output PDF. Default: "<patient_id>/lvh_curves.pdf")

• dpi (int)

Return type:

Figure

Returns:

matplotlib Figure

plot_dlvh(save=None, dpi=150)

Generate 2-D DLVH figures – one PNG per structure.

Parameters:

• save (output directory. Default: "<patient_id>/dlvh_2d/")

• dpi (int)

Return type:

list

Returns:

list of (structure_name, Path) tuples

save_all(output_dir=None, csv_name='dvh_metrics.csv', excel_name='dvh_metrics.xlsx', dpi=150)

Convenience method: save CSV, Excel, DVH PDF, LVH PDF, DLVH PNGs.

Parameters:

• output_dir (base output directory. Default: patient_id/)

• csv_name (filename for the CSV output)

• excel_name (filename for the Excel output)

• dpi (figure DPI for all plots)