surveff_cox: Wrapper for Cox Survival Effect Estimation with Variance
In PSsurvival: Propensity Score Methods for Survival Analysis

surveff_cox

R Documentation

Wrapper for Cox Survival Effect Estimation with Variance

Description

High-level wrapper combining propensity score estimation, weighting (with optional trimming), survival function estimation, and variance estimation using bootstrap. Unlike Weibull-based estimation, Cox censoring scores do not support analytical variance; bootstrap is always used.

Usage

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

Arguments

`data`	Data frame (possibly processed by data validation).
`treatment_var`	Name of treatment variable.
`ps_formula`	Formula for propensity score model.
`time_var`	Name of time variable.
`event_var`	Name of event indicator (1 = event, 0 = censored).
`censoring_formula`	Formula for censoring score model.
`eval_times`	Numeric vector of time points. If NULL, uses all unique event times.
`estimand`	Target estimand: "ATE", "ATT", or "overlap". 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. Required if trim = "symmetric".
`alpha`	Percentile for asymmetric trimming. Required if trim = "asymmetric".
`contrast_matrix`	Optional matrix for treatment differences. Each row represents one contrast with exactly two non-zero elements: -1 and 1. Column names must match treatment levels. For binary treatment, ignored (always estimates S1-S0). For >2 groups, required to estimate differences (otherwise returns NULL).
`B`	Number of bootstrap iterations. Default 100.
`parallel`	Logical. Use parallel bootstrap via `mclapply`. Default FALSE.
`mc.cores`	Number of cores for parallel bootstrap. Default 2.
`seed`	Random seed for bootstrap reproducibility. Default NULL.
`censoring_control`	Control parameters for `coxph()`. Default `list()`.
`ties`	Tie handling method for Cox model. Default "efron".
`ps_control`	Control parameters for PS 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

This function implements the complete estimation workflow:

**Without trimming:** 1. Estimate propensity scores on full data 2. Estimate weights from PS 3. Estimate censoring scores on full data 4. Estimate survival functions 5. Estimate differences (if applicable) 6. Estimate variances using bootstrap

**With trimming:** 1. Estimate propensity scores on full data (PS_full) 2. Use PS_full to identify observations to trim 3. Re-estimate propensity scores on trimmed data (PS_trimmed) 4. Estimate weights from PS_trimmed 5. Estimate censoring scores on trimmed data 6. Estimate survival functions on trimmed data 7. Estimate differences (if applicable) 8. Estimate variances using bootstrap

**Treatment differences:** - Binary (2 groups): Always estimates S1 - S0 (second level minus first level), ignoring contrast_matrix even if provided. - Multiple groups (>2): Requires contrast_matrix to estimate differences. Returns NULL for difference_* if contrast_matrix not provided.

**Variance estimation for differences:** - Binary: Differences columns in each bootstrap sample, calculates sample variance across B trials. - Multiple groups: Always uses bootstrap method.

Value

List containing:

`survival_estimates`	Matrix [time x J] of survival function estimates.
`survival_variances`	Matrix [time x J] of survival function variances.
`difference_estimates`	Matrix [time x K] of treatment differences (NULL for >2 groups without contrast_matrix).
`difference_variances`	Matrix [time x K] of difference variances (NULL for >2 groups without contrast_matrix).
`eval_times`	Time points evaluated.
`treatment_levels`	Treatment level values.
`n_levels`	Number of treatment levels.
`contrast_matrix`	Contrast matrix used (NULL if not applicable).
`surv_result`	Output from `surv_cox()`.
`variance_method`	Always "bootstrap" for Cox-based estimation.
`boot_result`	Bootstrap results.