WA_fit: While-Alive Regression (WA) for Composite Endpoints

In WAreg: While-Alive Regression for Composite Endpoints with Cluster-Robust Inference

While-Alive Regression (WA) for Composite Endpoints

Description

Fits the while-alive regression model targeting the while-alive loss rate for composite endpoints with recurrent and terminal events. Time-varying covariate effects are represented via user-chosen time bases (e.g., B-spline, piecewise polynomial, interval-local). Robust inference supports cluster-randomized trials (CRTs) via cluster-robust variance; if cluster = NULL, IID (subject-as-cluster) variance is used.

Usage

WA_fit(
  formula,
  data,
  id,
  cluster = NULL,
  knots,
  tau_grid,
  basis = c("il", "pl", "bz", "ns", "ms", "st", "tl", "tf"),
  degree = 1,
  link = c("log", "identity"),
  w_recur,
  w_term,
  ipcw = c("km", "cox"),
  ipcw_formula = ~1
)

Arguments

formula	A Surv(time, status) ~ RHS formula. time and status must exist in data. The RHS contains baseline covariates (no explicit time-varying covariates here; time-variation is induced via the chosen basis).
data	Long-format data frame with one row per event/checkpoint per subject, containing time, status, id, optional cluster, and RHS covariates.
id	Character scalar; subject ID column name.
cluster	Optional character scalar; cluster column name for CRT-robust inference. If NULL, IID inference treats each subject as its own cluster.
knots	Numeric vector (length \ge 2) specifying the basis boundaries and optional interior knots that define the time basis shape.
tau_grid	Numeric vector of evaluation times used to stack the estimating equations. Independent of knots.
basis	One of "il","pl","bz","ns","ms","st","tl","tf": interval-local ("il"), piecewise polynomial ("pl"), B-spline ("bz"), natural spline ("ns"), M-spline ("ms", requires splines2), step ("st"), truncated linear ("tl"), or time-fixed ("tf").
degree	Integer degree for bases that use it (e.g., "bz", "pl", "ns", "ms").
link	Link function: "log" (default) or "identity".
w_recur	Numeric vector of weights for each recurrent event type. Its length must match the number of recurrent status codes in data (i.e., excluding 0 for censoring and the max code for terminal).
w_term	Numeric scalar; weight for the terminal event.
ipcw	IPCW method: "km" or "cox".
ipcw_formula	A one-sided formula specifying RHS covariates for the IPCW Cox model when ipcw = "cox" (e.g., ~ x1 + x2). Ignored for ipcw = "km".

Details

The estimating equations solve E[Z(t)\{L(t) - \mu_\beta(t)X_{\min}(t)\}V/G]=0 over tau_grid, where L(t) is the weighted composite loss (recurrent+terminal), \mu_\beta(t) the while-alive loss rate under the chosen link, X_{\min}(t) = \min(T, t), V the at-risk/terminal indicator, and G the censoring survival modeled via ipcw.

Value

An object of class "WA" with elements:

• est: named coefficient vector.

• vcov: cluster-robust variance matrix.

• se: standard errors.

• converged: logical.

• basis, degree, link, Z_cols, knots, tau_grid, id_var, cluster_var, w_recur, w_term, status_codes, formula.

Examples

ex_dt <- crt_dt[crt_dt$cluster %in% c(1,2,3,4,7,10), ]
fit <- WA_fit(
  survival::Surv(time, status) ~ trt + Z1 + Z2,
  data     = ex_dt,
  id       = "id",
  cluster  = "cluster",
  knots    = seq(0, max(ex_dt$time, na.rm = TRUE), length.out = 6),
  tau_grid = seq(0, max(ex_dt$time, na.rm = TRUE), length.out = 6),
  basis    = "bz", degree = 1, link = "log",
  w_recur  = c(1, 1), w_term = 2,
  ipcw     = "km"
)
s <- summary(fit)
nd <- unique(ex_dt[, c("trt","Z1","Z2")])
plot(fit, newdata = nd,
     t_seq = seq(0, max(fit$tau_grid), length.out = 200),
     id = 1, mode = "wa", smooth = TRUE)

WAreg documentation built on March 6, 2026, 5:07 p.m.