ehrapy.tools.cox_ph_adjusted_curves

ehrapy.tools.cox_ph_adjusted_curves#

ehrapy.tools.cox_ph_adjusted_curves(edata, cph, strata, *, duration_col, event_col, method='average', reference_values=None, n_bootstrap=200, ci_alpha=0.05, times=None, layer=None, uns_key='cox_ph_adjusted_curves')[source]#

Compute CoxPH adjusted survival curves stratified by a grouping variable.

Adjusted survival curves account for differences in baseline covariates between groups, allowing fairer comparison of survival outcomes in observational cohorts where groups may not be balanced. This mirrors the functionality of R’s survminer::surv_adjustedcurves(). The results will be stored in the .uns slot of the data object under the key ‘cox_ph_adjusted_curves’, unless specified otherwise in the uns_key parameter. See Therneau, Crowson & Atkinson (2015), ‘Adjusted Survival Curves’: https://cran.r-project.org/web/packages/survival/vignettes/adjcurve.pdf.

Parameters:

  • edata (EHRData) – Central data object.

  • cph (CoxPHFitter) – Fitted CoxPHFitter, as returned by cox_ph().

  • strata (str) – Name of the column to stratify by. Must be present in the data and should not be included in the Cox model formula.

  • duration_col (str) – The name of the column that contains the subjects’ lifetimes.

  • event_col (str) – The name of the column that specifies whether the event has been observed or censored. Column values are True if the event was observed, False if the event was lost (right-censored).

  • method (Literal['average', 'conditional'], default: 'average') – The method used to compute adjusted survival curves. Options are: * ‘average’ one population-averaged curve per group, no rebalancing. * ‘conditional’ one curve per group for a synthetic reference patient with cohort-average covariates, varying only the strata variable.

  • reference_values (Mapping[str, str | int | float] | None, default: None) – A dict of values to override the default reference patient values for method = ‘conditional’ (mean for continuous, mode for categorical).

  • n_bootstrap (int, default: 200) – Number of bootstrap resamples used to compute confidence intervals. Only used when method is ‘average’.

  • ci_alpha (float, default: 0.05) – Significance level for confidence intervals.

  • times (ndarray | None, default: None) – Evaluation time grid. Defaults to 100 evenly-spaced points from 0 to the maximum observed time.

  • layer (str | None, default: None) – The layer to use when reconstructing the covariate data for prediction.

  • uns_key (str, default: 'cox_ph_adjusted_curves') – The key to use for the .uns slot in the data object.

Return type:

None

Returns:

None. Results are stored in edata.uns[uns_key].

Examples

>>> import ehrdata as ed
>>> import ehrapy as ep
>>> edata = ed.dt.mimic_2()
>>> cph = ep.tl.cox_ph(
...     edata, "mort_day_censored", "censor_flg", formula="gender_num + afib_flg + day_icu_intime_num"
... )
>>> ep.tl.cox_ph_adjusted_curves(
...     edata,
...     cph,
...     strata="gender_num",
...     duration_col="mort_day_censored",
...     event_col="censor_flg",
... )