rmst_diff()

Compute the RMST difference between two groups and return a tidy DataFrame.

Usage

rmst_diff(
    surv,
    tau,
    group=None,
    *,
    data=None,
    strata=None,
    conf_level=0.95,
)

A convenience wrapper around rmst_test() with estimand="difference" that returns the result as a single-row DataFrame rather than an RMSTResult object. This is useful when you want to feed the comparison directly into a summary table or pipeline.

Parameters

surv: Surv | Outcome | str: A right-censored Surv response, built with gw.Surv(time=..., event=...). 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. Should be a clinically meaningful horizon (e.g., 365 days for one-year RMST).
group: Any = None: Group labels, one per observation. Must have exactly two unique levels.
strata: Any | None = None: Stratification variable for stratified RMST comparison. If provided, per-group RMST estimates are computed within each stratum and pooled with inverse-variance weights.
conf_level: float = 0.95: Confidence level for the confidence interval (the default is 0.95).
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: A single-row DataFrame with columns group1, group2, rmst1, rmst2, difference, se, lower_ci, upper_ci, statistic, and p_value.

Examples

Compute the one-year RMST difference between sexes in the lung cancer dataset:

import greenwood as gw

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

# Compute the one-year RMST difference as a tidy DataFrame
gw.rmst_diff("Surv(time, status) ~ sex", tau=365, data=lung)

shape: (1, 10)

group1	group2	rmst1	rmst2	difference	se	lower_ci	upper_ci	statistic	p_value
i64	i64	f64	f64	f64	f64	f64	f64	f64	f64
1	2	241.495085	297.46541	-55.970324	14.958126	-85.287712	-26.652936	-3.741801	0.000183