surveff: Survival Effect Estimation with Propensity Score Weighting

In PSsurvival: Propensity Score Methods for Survival Analysis

Survival Effect Estimation with Propensity Score Weighting

Description

Main user interface for estimating counterfactual survival functions and treatment effects using propensity score weighting and inverse probability of censoring weighting. Supports binary and multiple treatment groups with various weighting schemes (ATE, ATT, overlap) and optional trimming.

Usage

surveff(
  data,
  ps_formula,
  censoring_formula,
  eval_times = NULL,
  estimand = "ATE",
  att_group = NULL,
  trim = NULL,
  delta = NULL,
  alpha = NULL,
  contrast_matrix = NULL,
  censoring_method = "weibull",
  variance_method = NULL,
  B = 100,
  parallel = FALSE,
  mc.cores = 2,
  seed = NULL,
  censoring_control = NULL,
  ties = "efron",
  ps_control = list(),
  boot_level = "full"
)

Arguments

data	Data frame containing treatment, outcome, and covariates.
ps_formula	Formula for propensity score model: treatment ~ covariates.
censoring_formula	Formula for censoring model: Surv(time, event) ~ covariates. Event should be coded as 1=event, 0=censored. Use I(1-event) if reversed.
eval_times	Numeric vector of time points for evaluation. If NULL (default), uses all unique event times.
estimand	Target estimand: "ATE" (average treatment effect), "ATT" (average treatment effect on the treated), or "overlap" (overlap weighting). Default "ATE".
att_group	Target group for ATT. Required if estimand = "ATT".
trim	Trimming method: "symmetric" or "asymmetric". Default NULL (no trimming).
delta	Threshold for symmetric trimming (e.g., 0.1). Required if trim = "symmetric".
alpha	Percentile for asymmetric trimming (e.g., 0.05). Required if trim = "asymmetric".
contrast_matrix	Optional matrix for treatment differences in multiple group settings. Each row defines one contrast with exactly two non-zero elements: -1 and 1. Column names must match treatment levels. For binary treatment, always estimates second level minus first level (S1 - S0), ignoring this parameter.
censoring_method	Method for censoring score estimation: "weibull" or "cox". Default "weibull".
variance_method	Variance estimation method: "analytical" (binary treatment with Weibull censoring only) or "bootstrap". Default "analytical" for binary Weibull, "bootstrap" otherwise. Cox censoring always uses bootstrap.
B	Number of bootstrap iterations. Default 100. Used only if variance_method = "bootstrap".
parallel	Logical. Use parallel bootstrap computation? Default FALSE.
mc.cores	Number of cores for parallel bootstrap. Default 2.
seed	Random seed for bootstrap reproducibility. Default NULL.
censoring_control	Control parameters passed to censoring model fitting function. For Weibull: passed to survreg(), default list(maxiter = 350). For Cox: passed to coxph(), default list().
ties	Tie handling method for Cox models. Default "efron". Ignored for Weibull.
ps_control	Control parameters for propensity score model. Default list().
boot_level	Bootstrap sampling level: "full" (default) or "strata". "full" resamples from entire dataset (standard for observational studies). "strata" resamples within each treatment group preserving group sizes (useful when treatment assignment follows a stratified or fixed-ratio design). Only used if variance_method = "bootstrap".

Details

**Variance Estimation:** - Analytical: Binary treatment with Weibull censoring only (M-estimation). - Bootstrap: All settings (resamples entire pipeline). - Cox: Always uses bootstrap.

**Treatment Effects:** - Binary: S1 - S0 (second level minus first). - Multiple groups: Requires contrast_matrix for pairwise comparisons.

Value

List containing:

survival_estimates	Matrix [time x J] of survival function estimates for each group.
survival_se	Matrix [time x J] of standard errors for survival functions.
difference_estimates	Matrix [time x K] of treatment effect estimates. For binary treatment: single column with S1-S0. For multiple groups: contrasts from contrast_matrix, or NULL if not provided.
difference_se	Matrix [time x K] of standard errors for treatment effects.
eval_times	Time points evaluated.
treatment_levels	Sorted unique treatment values.
n_levels	Number of treatment groups.
n	Sample size (complete cases after data validation).
included	Logical vector [n] indicating inclusion in analysis. TRUE = included, FALSE = excluded due to trimming.
estimand	Estimand used.
censoring_method	Censoring method used.
variance_method	Variance method used.
contrast_matrix	Contrast matrix used (NULL if not applicable).
ps_model	Fitted propensity score model (glm or multinom object).
censoring_models	Named list of fitted censoring models by treatment group.
weights	Numeric vector [n] of final weights (0 for trimmed observations).
trim_summary	Data frame with trimming summary by treatment group.
ess	Named numeric vector of effective sample size by treatment group.
boot_result	Bootstrap results (NULL if analytical variance used).

Examples

# Example 1: Binary treatment with overlap weighting and Weibull censoring model
data(simdata_bin)
result1 <- surveff(
  data = simdata_bin,
  ps_formula = Z ~ X1 + X2 + X3 + B1 + B2,
  censoring_formula = survival::Surv(time, event) ~ X1 + B1,
  estimand = "overlap",
  censoring_method = "weibull"
)
summary(result1)
plot(result1)

# Example 2: Multiple treatments with ATE and Cox censoring model
data(simdata_multi)
result2 <- surveff(
  data = simdata_multi,
  ps_formula = Z ~ X1 + X2 + X3 + B1 + B2,
  censoring_formula = survival::Surv(time, event) ~ X1 + B1,
  estimand = "ATE",
  censoring_method = "cox",
  variance_method = "bootstrap",
  B = 100
)
summary(result2)

PSsurvival documentation built on Dec. 9, 2025, 9:07 a.m.