PyPlanAnalysis.NTCP

NTCP scoring engine: NTCPConfig selects which models to run, NTCPModelBase loads one model’s metadata from the bundled parameter workbook and dispatches to its NTCP__* implementation function. See NTCP Models Reference for a curated overview table of every model.

default_ntcp_params_path()

Path to the NTCP model-parameter workbook bundled with the package (PyPlanAnalysis/data/NTCPModels_params.xlsx). Used automatically by NTCPModelBase when no explicit df_models_path is supplied, so installed users get working NTCP calculations out of the box.

class NTCPConfig(roi_overrides=<factory>, ctv_name=None, models=<factory>)

Bases: object

Selects which NTCP toxicity models to compute in AnalysisResults.CalcNTCP().

Parameters:

• models (list of str) – Subset of the model names below (must match the model_name column of the bundled NTCPModels_params.xlsx workbook). Default: all models listed below.

• roi_overrides (dict) – Optional {model_name: roi_name} mapping. When a model name is present here, its exact roi_name (must match a value in metrics_df["ROI_Name"]) is used directly instead of the OAR substring match from the parameter workbook — lets you point a model at a specific contoured ROI on a per-patient basis, even if it doesn’t match the workbook’s OAR column. Default: empty (use the workbook’s OAR-based matching for every model).

• ctv_name (str or None) – Optional exact ROI_Name to use as “the CTV” reference for geometry-based ipsi/contra selection (see NTCPModelBase.define_side). Default: None, which falls back to the first ROI (in table order) whose name contains “CTV” (case-insensitive).

Notes

Each model name maps to one NTCP__* implementation function in this module (brain/head-and-neck late- and acute-toxicity endpoints from Dutz, De Marzi, Burman, Gondi, Kong, Lee, Bender and Batth).

roi_overrides: dict

ctv_name: str = None

models: list

class NTCPModelBase(model_name, df_models_path, roi_name=None, ctv_name=None)

Bases: object

Loads one NTCP model’s metadata from the parameter workbook and dispatches to its implementation function.

Parameters:

• model_name (str) – Must match a value in the model_name column of the parameter workbook (see NTCPConfig.models for the full list).

• df_models_path (str or Path, optional) – Path to the NTCP parameter workbook (.xlsx). Default: None, which resolves to the workbook bundled with the package via default_ntcp_params_path().

• roi_name (str, optional) – Exact ROI_Name to use for this model, bypassing the workbook’s OAR substring match entirely. Must match a value in metrics_df["ROI_Name"] (case-insensitive exact match). Default: None (use OAR-based matching).

• ctv_name (str, optional) – Exact ROI_Name to treat as “the CTV” for geometry-based ipsi/contra selection. Default: None, which falls back to the first ROI (in table order) whose name contains “CTV”.

OAR_name

Organ-at-risk name this model applies to.

Type:

str

numberOfVariables

Number of covariates the model’s implementation function expects.

Type:

int

parameterNames

DVH/LVH metric column-name suffixes to pull from the metrics DataFrame for each covariate, in order.

Type:

list of str

side

Laterality selection rule, inferred from model_name.

Type:

{“ipsi”, “contra”, None}

impl_fn

The NTCP__* function implementing this model’s formula.

Type:

callable

define_side(vRBE_model, dfi_dvh, parameterName)

Resolve which structure (ROI) to use when a model applies to a laterality-specific OAR (e.g. “Cochlea ipsi” vs “Cochlea contra”) and the metrics DataFrame has more than one ROI matching self.OAR_name.

Selection is geometry-based when possible: the candidate ROI whose center of mass is closest to the CTV’s center of mass is “ipsi”, the farthest is “contra” (see _define_side_by_geometry/get_roi_center_of_mass). If center-of-mass data isn’t available for the CTV or for every candidate ROI, this falls back to the previous dose-value heuristic (candidate with the highest mean dose = ipsi, lowest = contra).

Parameters:

• vRBE_model (str) – Dose-type/RBE-model label prefix used in the metrics column names (e.g. “Phys”, “RBE1.1”, “mcnamara”).

• dfi_dvh (pandas.DataFrame) – The patient’s per-structure metrics table (AnalysisResults.metrics_df).

• parameterName (str) – Metric column-name suffix to compare across candidate ROIs.

Returns:

str or None – The chosen ROI_Name value, or None if no ROI matches.

compute_x(vRBE_model, dfi_dvh, roi)

Build the covariate vector x this model’s impl_fn expects, by pulling self.parameterNames columns for the matched ROI(s) out of the metrics DataFrame.

Parameters:

• vRBE_model (str) – Dose-type/RBE-model label prefix (see define_side).

• dfi_dvh (pandas.DataFrame) – Patient metrics table (AnalysisResults.metrics_df).

• roi (str) – ROI name defined on (compute_NTCP).

Returns:

list of float – One value per covariate, in self.parameterNames order. Entries are np.nan where the required ROI/metric could not be found.

compute_NTCP(vRBE_model, dfi_dvh)

Compute this model’s NTCP for one patient and one dose type. Define ipsi/contra first based on COM, mean dose as fallback

Parameters:

• vRBE_model (str) – Dose-type/RBE-model label prefix (see define_side).

• dfi_dvh (pandas.DataFrame) – Patient metrics table (AnalysisResults.metrics_df).

Returns:

float or None – NTCP in percent (0-100), rounded to 4 decimals. Returns None if any required covariate is missing/NaN.

Model implementation functions

PyPlanAnalysis.NTCP.py

computes different NTCP following details in /Utils/NTCPModels_params.xlsx. It works both with variable and fixed RBE models for proton therapy.

npNan(x)

Fallback implementation for an unrecognised model name; always returns NaN.

NTCP__Alopecia_G1_12m__1(x, beta_0=-1.88, beta_1=0.15)

Alopecia grade >=1, 12 months after PBT Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates: x[0] = Skin V45Gy(RBE) in cm^-3.

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__Alopecia_G1_12m__2(x, beta_0=-6.38, beta_1=0.15)

Alopecia grade ≥1_12 months after PBT Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1]

NTCP__Alopecia_G1_24m__1(x, beta_0=-1.7, beta_1=0.048)

Alopecia grade ≥1_24 months after PBT Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__Alopecia_G1_24m__2(x, beta_0=-3.18, beta_1=0.068)

Alopecia grade ≥1_24 months after PBT Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__Alopecia_G1_acute(x, beta_0=-0.94, beta_1=0.1)

Alopecia grade >=1 (CTCAE, Common Terminology Criteria for Adverse Events) Acute Dutz et al. 2019

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__Alopecia_G2_acute(x, beta_0=-1.33, beta_1=0.081)

Alopecia grade >=2 (CTCAE, Common Terminology Criteria for Adverse Events) Acute Dutz et al. 2019

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__Blindness_5y(x, TD50=65.0, m=0.14)

Blindness Chiasm and optic nerves gEUD, a = 4.0 5 years post-RT Burman et al. 1991

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• TD50 (float) – Fitted model coefficient (see reference above for origin/units).

• m (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__BrainNecrosis_5y(x, D50=109.0, gamma=2.8)

Brain necrosis Brain-CTV and Brainstem Dmax (EQD2) 5 years post-RT Bender et al. 2012

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• D50 (float) – Fitted model coefficient (see reference above for origin/units).

• gamma (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__CataractRequiringIntervention_5y(x, TD50=18.0, m=0.27)

Cataract requiring intervention Lenses gEUD 5 years post-RT Burman et al. 1991

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• TD50 (float) – Fitted model coefficient (see reference above for origin/units).

• m (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__DelayedRecall_1_5y(x, EQD_2_50=14.88, m=0.54)

Delayed recall (on Wechsler Memory scale III Word Lists) Bilateral hippocampi D40% (EQD2) 1.5 years post-RT Gondi et al. 2012

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• EQD_2_50 (float) – Fitted model coefficient (see reference above for origin/units).

• m (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__EndocrineDysfunction_late(x, TD50=60.5, gamma50=5.2)

Endocrine dysfunction (CTCAE, Common Terminology Criteria for Adverse Events) Pituitary gEUD, a = 6.4 At least 0.5 – 2 years post-RT De Marzi et al. 2015

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• TD50 (float) – Fitted model coefficient (see reference above for origin/units).

• gamma50 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__Erythema_G1_acute(x, beta_0=1.0, beta_1=0.085)

Erythema grade ≥ 1 Skin V35Gy(RBE), absolute volume Acute Dutz et al. 2019

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__Erythema_G2_acute(x, beta_0=-1.54, beta_1=0.056)

Erythema grade ≥ 2 (CTCAE, Common Terminology Criteria for Adverse Events) Skin V35Gy(RBE), absolute volume Acute Dutz et al. 2019

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float NTCP probability in [0, 1] .

NTCP__Fatigue_G1_24m(x, beta_0=-1.52, beta_1=0.021, beta_2=-1.16)

Fatigue grade ≥ 1_24 months after PBT x[0] BrainStem D2% in Gy(RBE)^-(1) x[1] CTx == 0: patient recieved no chemotherapy

CTx == 1: patient recieved chemotherapy

Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_2 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float NTCP probability in [0, 1] .

NTCP__Fatigue_G1_acute(x, beta_0=-0.9, beta_1=0.027, beta_2=1.28)

Fatigue grade >=1 (CTCAE, Common Terminology Criteria for Adverse Events) x[0] Brain-CTV(Gy), D2% x[1] female: gender = 1

male: gender = 0

Acute Dutz et al. 2019

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_2 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float NTCP probability in [0, 1] .

NTCP__HearingImpairment_G1_12m__1(x, beta_0=-3.03, beta_1=0.038)

Hearing impairment grade ≥1_12 months after PBT Dmean == Cochlea ipsi Dmean in Gy(RBE)^-(1) Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__HearingImpairment_G1_12m__2(x, beta_0=-7.02, beta_1=0.032, beta_2=0.072)

Hearing impairment grade ≥1_12 months after PBT x[0] Dmean = Cochlea ipsi Dmean in Gy(RBE)^-(1) x[1] Age = Age in years Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_2 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__HearingImpairment_G1_24m(x, beta_0=-3.48, beta_1=0.05)

Hearing impairment grade ≥1_24 months after PBT Cochlea ipsi Dmean in Gy(RBE)^-(1) Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__HearingLoss_late(x, TD50=56.0, gamma50=2.9)

Hearing loss (CTCAE, Common Terminology Criteria for Adverse Events) Cochlea gEUD, a = 1.2 At least 0.5 – 2 years post-RT De Marzi et al. 2015

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• TD50 (float) – Fitted model coefficient (see reference above for origin/units).

• gamma50 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1].

NTCP__MemoryImpairment_G1_12m(x, beta_0=-2.32, beta_1=0.023)

Memory impairment grade ≥1_12 months after PBT Hippocampi D2% in Gy(RBE)^-(1) Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__MemoryImpairment_G1_24m(x, beta_0=-1.77, beta_1=6.5)

Memory impairment grade ≥1_24 months after PBT Brain-CTV V35Gy(RBE) as fraction of the total volume Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__MemoryImpairment_G2_12m(x, beta_0=-3.42, beta_1=5.02)

Memory impairment grade ≥2_12 months after PBT Brain-CTV V25Gy(RBE) as fraction of the total volume Late Dutz et al. 2021

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__OcularToxicity_G2_acute(x, beta_0=-5.174, beta_1=0.205)

Ocular toxicity grade ≥ 2 (RTOG, Radiation Therapy Oncology Group) Ipsilateral lacrimal gland Dmax Acute Batth et al. 2013

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__TemporalLobeInjury_5y(x, beta_0=-18.61, beta_1=0.227)

Temporal lobe injury Dmax = Temporal lobe Dmax 5 years post-RT Kong et al. 2016

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• beta_0 (float) – Fitted model coefficient (see reference above for origin/units).

• beta_1 (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .

NTCP__Tinnitus_G2_late(x, TD50=46.52, m=0.35)

Tinnitus grade ≥ 2 (LENT-SOMA, late effects of normal tissues - subjective, objective, management) Cochlea Dmean 1–2 years post-RT Lee et al. 2015

Parameters:

• x (list) – Model covariates, in the order defined by the NTCP parameter workbook for this model (see NTCPModelBase.parameterNames).

• TD50 (float) – Fitted model coefficient (see reference above for origin/units).

• m (float) – Fitted model coefficient (see reference above for origin/units).

Returns:

float – NTCP probability in [0, 1] .