## time_dependent_auc()


IPCW (Uno) time-dependent AUC at specified times.


Usage

``` python
time_dependent_auc(
    surv,
    marker,
    times,
)
```


Computes the cumulative-dynamic AUC at each requested time using the inverse-probability- of-censoring-weighted (IPCW) estimator of Uno et al. (2011). At each time t, *cases* are subjects who experienced an event by t and *controls* are subjects still at risk after t. The AUC measures how well the marker separates the two groups, correcting for censoring bias via IPCW weights.

**Interpretation**:

- 0.5: Random discrimination (marker carries no prognostic information at t).

- > 0.5: Better-than-random. The marker ranks earlier-failing subjects higher.

- 1.0: Perfect discrimination at t.

- AUC tends to vary with t. Use [integrated_auc()](integrated_auc.md#greenwood.integrated_auc) for a single summary.

**Higher marker = higher risk** convention: the marker should be on a scale where larger values indicate greater hazard (e.g., a Cox linear predictor, a predicted cumulative incidence, or a biomarker positively associated with failure). To use a *lower-is-worse* marker (e.g., predicted survival probability), negate it first.


## Parameters


`surv: Surv`  
A right-censored [Surv](Surv.md#greenwood.Surv) response.

`marker: Any`  
Risk score for each subject (one value per observation). Higher values should indicate higher risk (earlier expected failure). Accepts a 1-D array, pandas/Polars Series, or Python sequence.

`times: Any`  
Evaluation times where the AUC is computed. 1-D array-like. Times before the first event or after the last observation yield `nan`.


## Returns


`ndarray`  
AUC at each requested time, shape `(len(times),)`. Values are in \[0, 1\] or `nan` when a time has no cases or no controls.


## Details

**Uno et al. (2011) estimator**: For time t let

- cases: \mathcal{C}(t) = \\i : T_i \le t,\\ \Delta_i = 1\\
- controls: \mathcal{K}(t) = \\j : T_j \> t\\
- IPCW weight for case i: w_i = \hat{G}(T_i-)^{-2}, where \hat{G} is the Kaplan-Meier estimate of the *censoring* survival function.

 \widehat{AUC}(t) = \frac{\displaystyle\sum\_{i \in \mathcal{C}(t)} w_i \Bigl\[\\\\j\in\mathcal{K}(t):\eta_j \< \eta_i\\ + \tfrac{1}{2}\\\\j\in\mathcal{K}(t):\eta_j = \eta_i\\\Bigr\]} {\|\mathcal{K}(t)\| \cdot \displaystyle\sum\_{i \in \mathcal{C}(t)} w_i} 

When G(t) = 1 (no censoring) the estimator reduces to the empirical AUC of the binary problem "case vs. control at t".

**Relationship to concordance**: The Harrell C-statistic is closely related to the time-averaged AUC across all event times. Use [integrated_auc()](integrated_auc.md#greenwood.integrated_auc) to obtain a single time-averaged summary that is directly comparable to the C-index.


## References

Uno H., Cai T., Pencina M.J., D'Agostino R.B., Wei L.J. (2011). On the C-statistics for evaluating overall adequacy of risk prediction procedures with censored survival data. *Statistics in Medicine*, 30(10), 1105-1117.


## Examples

Fit a Cox model on the `lung` dataset and compute its time-dependent AUC using the linear predictor as the risk marker.


``` python
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 time-dependent AUC at three clinically relevant horizons
lp = cox.predict(type="lp")
auc = gw.time_dependent_auc(y, lp, times=[180, 365, 540])
auc
```


    array([0.64152627, 0.5943264 , 0.6023971 ])


Compare discrimination of two models via [integrated_auc()](integrated_auc.md#greenwood.integrated_auc):


``` python
# Summarize discrimination as a single time-averaged AUC
ibs = gw.integrated_auc(y, lp, times=[180, 365, 540])
ibs
```


    0.6084157733720682