PyPlanAnalysis.metrics

DVH/LVH metric computation (Dx%, Vx, gEUD, EQD2, D_Lx%, L_Dx%) and per-structure radiobiological parameter configuration.

PyPlanAnalysis.metrics

DVH/LVH metric computation (Dx%, Vx, gEUD, EQD2, D_Lx%, L_Dx%) and per-structure radiobiological parameter configuration.

class RadiobiologyConfig(alpha_beta_map=<factory>, alpha_beta_default=2.0, geud_a_map=<factory>, geud_a_default=1.0)[source]

Bases: object

Per-structure radiobiological parameters.

Parameters:

  • alpha_beta_map (dict) – Keys are substrings of structure names (case-insensitive). Values are α/β [Gy].

  • alpha_beta_default (float) – Fallback α/β when no key matches.

  • geud_a_map (dict) – Keys are substrings of structure names. Values are gEUD parameter a.

  • geud_a_default (float) – Fallback gEUD a.

alpha_beta_map: dict
alpha_beta_default: float = 2.0
geud_a_map: dict
geud_a_default: float = 1.0
get_alpha_beta(structure_name)[source]
Return type:

float

Parameters:

structure_name (str)

get_geud_a(structure_name)[source]
Return type:

float

Parameters:

structure_name (str)

class MetricConfig(dx=<factory>, lx=<factory>, vx=<factory>, LET_thr=2.5, compute_eqd2=True, compute_geud=True, dvh_bins=1000, lvh_bins=1000, dlvh_dose_bins=1000, dlvh_let_bins=1000, New_grid=<factory>)[source]

Bases: object

Configure which DVH metrics to compute.

Parameters:

  • dx (list of int/float) – Dx% points (% volume). e.g. [2, 5, 50, 95, 98]

  • lx (list of int/float) – Lx% points (% volume). e.g. [2, 50, 98]

  • vx (list of int/float) – Vx dose thresholds [Gy(RBE)]. e.g. [20, 30, 40, 50]

  • LET_thr (float) – LETd threshold used to consider dirty dose (D where L>LET_thr) [#keV/um]

  • compute_eqd2 (bool) – Whether to compute EQD2 (requires alpha_beta).

  • compute_geud (bool) – Whether to compute gEUD.

  • dvh_bins (int) – Number of bins for DVH histograms.

  • lvh_bins (int) – Number of bins for LVH histograms.

  • dlvh_dose_bins (int) – Dose axis bins for 2-D DLVH.

  • dlvh_let_bins (int) – LET axis bins for 2-D DLVH.

  • New_grid (list)

dx: list
lx: list
vx: list
LET_thr: float = 2.5
compute_eqd2: bool = True
compute_geud: bool = True
dvh_bins: int = 1000
lvh_bins: int = 1000
dlvh_dose_bins: int = 1000
dlvh_let_bins: int = 1000
New_grid: list
compute_dvh_metrics(dose_voxels, voxel_vol_cc, label, metric_cfg, alpha_beta=3.0, geud_a=1.0, weights=None, n_fractions=30)[source]

Compute all requested DVH metrics for a 1-D voxel dose array.

Parameters:

  • dose_voxels (1-D array of dose values [Gy or Gy(RBE)], already masked)

  • voxel_vol_cc (volume of one voxel in cc)

  • label (prefix string for metric names (e.g. "phys", "RBE1.1"))

  • metric_cfg (MetricConfig instance)

  • alpha_beta (α/β ratio [Gy] for EQD2)

  • geud_a (gEUD parameter a)

  • weights (optional 1-D array of fractional volumes [0,1] per voxel.) – If None, binary mask assumed (all weights = 1). When provided, all metrics are volume-weighted.

  • n_fractions (int)

Return type:

dict

Returns:

dict of {metric_name (value})

compute_let_metrics(let_voxels, dose_voxels, lx_points, label='LET', weights=None)[source]

Compute LET summary metrics for a structure.

Lx% is defined exactly like Dx% but on the LET distribution: the minimum LETd in the highest-LET x% of the structure volume.

Parameters:

  • let_voxels (1-D array of LETd values [keV/µm])

  • dose_voxels (1-D array of physical dose values [Gy], same voxels)

  • lx_points (list of x values for Lx%)

  • label (prefix for metric names)

  • weights (optional fractional volumes [0,1] per voxel)

Return type:

dict

Returns:

dict of {metric_name (value})

compute_cumulative_histogram(values, n_bins, weights=None)[source]

Compute a weighted cumulative histogram (DVH or LVH style).

When weights are provided (fractional mask), each voxel contributes its fractional volume rather than 1 full voxel.

Return type:

tuple

Returns:

  • edges (bin edges (length n_bins + 1))

  • cum (cumulative volume fraction from 1 → 0 (length n_bins + 1))

Parameters:

  • values (ndarray)

  • n_bins (int)

  • weights (ndarray)

compute_2d_histogram(dose_voxels, let_voxels, dose_bins, let_bins)[source]

Compute 2-D dose-LET volume histogram (DLVH).

Return type:

tuple

Returns:

  • H (2-D array (dose_bins × let_bins), volume fractions)

  • dose_edges (dose bin edges)

  • let_edges (LET bin edges)

Parameters:

  • dose_voxels (ndarray)

  • let_voxels (ndarray)

  • dose_bins (int)

  • let_bins (int)