`hazardous.metrics`.km_calibration#

hazardous.metrics.km_calibration(y_calibration, times, pred_calibration, return_diff_at_t=False, alpha=2)#

KM-Calibration: marginal calibration score for survival models.

Measures how closely the mean predicted survival probability tracks the Kaplan-Meier marginal estimate. The score is:

\[\text{KM-Cal} = \frac{1}{t_{\max}} \int_0^{t_{\max}} \left|\bar{S}(t) - \hat{S}_{KM}(t)\right|^\alpha \, dt\]

where \(\bar{S}(t) = \frac{1}{n} \sum_{i=1}^n \hat{S}(t \mid \mathbf{x}_i)\) is the mean predicted survival probability and \(\hat{S}_{KM}(t)\) is the Kaplan-Meier estimate fitted on the calibration set.

The KM-Calibration score is a special case of the Aalen-Johansen calibration score for a single event type. The implementation of this metric is also available in SurvivalEval [Qi2024], a python library for survival analysis evaluation metrics.

Parameters:

y_calibrationarray-like of shape (n_samples, 2): Survival outcomes of the calibration set, with columns "event" (0 for censoring, 1 for the event) and "duration" (observed time).
timesarray-like of shape (n_times,): Time points at which the survival probability was predicted.
pred_calibrationarray-like of shape (n_samples, n_times): Predicted survival probabilities at times for the calibration set.
return_diff_at_tbool, default=False: If True, also return the pointwise difference \(\bar{S}(t) - \hat{S}_{KM}(t)\) at each time in times.
alphaint, default=2: Exponent applied to the pointwise difference before integration. When alpha=2, the score is squared (L2 calibration).

Returns:

km_calfloat: KM-Calibration score. A value of 0 indicates perfect marginal calibration.
diff_at_tndarray of shape (n_times,), optional: Pointwise difference \(\bar{S}(t) - \hat{S}_{KM}(t)\). Only returned when return_diff_at_t=True.

hazardous.metrics.km_calibration#

`hazardous.metrics`.km_calibration#