integrated_auc()

Time-averaged IPCW AUC across multiple time points.

Usage

integrated_auc(
    surv,
    marker,
    times,
    *,
    data=None,
)

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 | Outcome | str: A right-censored Surv response. An Outcome or a formula response such as 'Surv(time, status == 2)' is also accepted, with its columns read from data.
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.
data: Any = None: A data frame (pandas, Polars, PyArrow, DuckDB, a lazy frame, …) holding the columns named by the response and marker. When surv is an Outcome or a formula, rows with a missing value in any column used are dropped first, along with the matching rows of any arrays passed alongside.

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 name the response columns
lung = gw.load_dataset("lung", backend="polars")
death = gw.Outcome.surv(time="time", event="status")
cox = gw.CoxPH().fit(death, covariates=["age", "sex"], data=lung)

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

0.6084157733720682