bootstrap()

Bootstrap confidence interval for a Kaplan-Meier summary statistic.

Usage

Source

bootstrap(
    surv,
    statistic,
    *,
    data=None,
    by=None,
    weights=None,
    n_boot=1000,
    conf_level=0.95,
    ci_type="percentile",
    seed=None,
    tau=None,
    p=None,
    times=None,
)

Resamples subjects with replacement, fits a Kaplan-Meier estimator on each resample, and extracts the statistic of interest. The bootstrap distribution is then used to construct a confidence interval.

Parameters

surv: Surv | Outcome | str

A Surv response (right-censored or counting-process). An Outcome or a formula string such as 'Surv(time, status == 2) ~ sex' is also accepted, with its columns read from data. The right-hand side names the group column(s).

statistic: str | Callable[[KaplanMeier], float]

The quantity to bootstrap. Pass a string for built-in statistics:

  • "median": median survival time.
  • "rmst": restricted mean survival time (requires tau=).
  • "quantile": survival quantile (requires p=).
  • "survival": survival probability at a fixed time (requires times=).
  • "median_diff": difference in median survival between two groups (requires by=).
  • "rmst_diff": difference in RMST between two groups (requires by= and tau=).
  • "survival_diff": difference in survival probability at a fixed time between two groups (requires by= and times=).

Alternatively, pass a callable that takes a fitted KaplanMeier and returns a float.

by: Any = None

Grouping variable for two-sample comparisons. Required for "_diff" statistics. Must define exactly two groups.

weights: Any = None

Optional case weights passed through to each bootstrap KM fit.

n_boot: int = 1000

Number of bootstrap replicates (default 1000).

conf_level: float = 0.95

Confidence level (default 0.95).

ci_type: str = "percentile"

Confidence interval type: "percentile" (default), "normal", or "bca" (bias-corrected and accelerated).

seed: int | None = None

Random seed for reproducibility.

tau: float | None = None

Upper time limit for RMST statistics.

p: float | None = None

Quantile level for "quantile" statistic.

times: float | None = None

Time point for "survival" and "survival_diff" statistics.

data: Any = None
A data frame (pandas, Polars, PyArrow, DuckDB, a lazy frame, …) holding the columns named by the response, by, and weights. 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

BootstrapResult
Point estimate, standard error, confidence interval, and the full bootstrap distribution.

Examples

Bootstrap a 95% percentile confidence interval for the median survival time:

import greenwood as gw

lung = gw.load_dataset("lung", backend="polars")
death = gw.Outcome.surv(time="time", event="status")

gw.bootstrap(death, statistic="median", n_boot=500, seed=0, data=lung)
BootstrapResult (n_boot=500, ci_type='percentile')

  estimate      se  0.95LCL  0.95UCL
   310.000  23.330  283.475  363.000

Bootstrap the difference in restricted mean survival time (RMST) between two groups. The formula’s right-hand side defines the grouping variable (the same as by="sex") and tau= sets the time horizon:

gw.bootstrap(
    "Surv(time, status) ~ sex", statistic="rmst_diff", tau=365, n_boot=500, seed=0,
    data=lung,
)
BootstrapResult (n_boot=500, ci_type='percentile')

  estimate      se  0.95LCL  0.95UCL
   -55.970  14.961  -83.607  -25.160

Use a BCa (bias-corrected and accelerated) interval for better small-sample coverage:

gw.bootstrap(
    death, statistic="median", n_boot=500, ci_type="bca", seed=0, data=lung
)
BootstrapResult (n_boot=500, ci_type='bca')

  estimate      se  0.95LCL  0.95UCL
   310.000  23.330  269.000  353.000