pairwise_rmst_test()

Pairwise RMST tests for all group pairs with multiple-comparison correction.

Usage

Source

pairwise_rmst_test(
    surv,
    tau,
    group=None,
    *,
    data=None,
    estimand="difference",
    strata=None,
    correction="holm",
    conf_level=0.95,
    format=None,
)

Compares RMST between all pairs of groups, with optional multiple-comparison adjustment. This answers the question: “Which pairs of groups have significantly different RMST?” when you have more than two groups.

Parameters

surv: Surv | Outcome | str

A right-censored Surv response (time-to-event data). 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) and strata(x) terms set strata.

tau: float

The restriction time for RMST calculation.

group: Any = None

Group labels, one per observation. Can be array-like or categorical variable. Must have at least 2 unique levels to create pairs.

estimand: str = "difference"

Type of estimand: "difference" (default), "ratio", or "percentage_difference".

strata: Any | None = None

(Optional) Stratification variable. Each pairwise test is stratified by this factor.

correction: str = "holm"

Multiple-comparison adjustment: "holm" (default), "bh", "bonferroni", or "none".

conf_level: float = 0.95

Confidence level for intervals (the default is 0.95).

format: str | None = None

Output format: None (auto-detect), "pandas", "polars", or "pyarrow".

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

DataFrame
One row per pair of groups with columns group1, group2, rmst1, rmst2, estimate, se, lower_ci, upper_ci, statistic, p_value, and p_adjusted.

Details

All \binom{k}{2} pairwise comparisons are performed, where k is the number of unique group levels. The raw p-values are then adjusted for multiplicity using the chosen correction method. Holm’s step-down procedure (the default) controls the family-wise error rate without assuming independence between tests.

Examples

Compare one-year RMST across sex groups in the lung cancer dataset with Holm correction:

import greenwood as gw

# Load the data
lung = gw.load_dataset("lung", backend="polars")

# Run pairwise RMST comparisons with Holm-adjusted p-values
gw.pairwise_rmst_test("Surv(time, status) ~ sex", tau=365, format="polars", data=lung)
shape: (1, 11)
group1group2rmst1rmst2estimateselower_ciupper_cistatisticp_valuep_adjusted
i64i64f64f64f64f64f64f64f64f64f64
12241.495085297.46541-55.97032414.958126-85.287712-26.652936-3.7418010.0001830.000183