integrated_auc()

Time-averaged IPCW AUC across multiple time points.

Usage

Source

integrated_auc(
    surv,
    marker,
    times,
)

Summarises time_dependent_auc() into a single number via trapezoidal integration over the supplied time range. This provides a discrimination summary analogous to Harrell’s C-statistic but with explicit IPCW bias-correction for censoring.

Interpretation: Same scale as time_dependent_auc() (0.5 = random, 1.0 = perfect). Values of 0.6-0.7 indicate moderate and 0.7+ indicate strong discrimination.

Parameters

surv: Surv

A right-censored Surv response.

marker: Any

Risk score for each subject. Higher values indicate higher risk.

times: Any

Evaluation times (at least 2). The integrated AUC is computed as the area under the AUC curve from times[0] to times[-1], normalized by the time span. nan time points (no cases or controls) are dropped before integration.

Returns

float

Time-averaged AUC in [0, 1]. Higher is better.

Details

The integrated AUC is computed as the area under the time-dependent AUC curve (from time_dependent_auc()) divided by the time span, giving a single scalar summary of discrimination across the specified horizon. Time points that produce nan AUC values (no cases or no controls at that time) are dropped before integration.

Examples

Compute the integrated AUC of a Cox model’s linear predictor across three clinically relevant time horizons (6, 12, and 18 months):

import greenwood as gw

# Load data and build a right-censored response
lung = gw.load_dataset("lung", backend="polars")
y = gw.Surv.right(lung["time"], event=(lung["status"] == 2))
cox = gw.CoxPH().fit(y, lung[["age", "sex"]])

# Compute the time-averaged AUC across three horizons
lp = cox.predict(type="lp")
gw.integrated_auc(y, lp, times=[180, 365, 540])

0.6084157733720682