surveff_weibull: Wrapper for Weibull Survival Effect Estimation with Variance
In PSsurvival: Propensity Score Methods for Survival Analysis

surveff_weibull

R Documentation

Wrapper for Weibull Survival Effect Estimation with Variance

Description

High-level wrapper combining propensity score estimation, weighting (with optional trimming), survival function estimation, and variance estimation (analytical or bootstrap).

Usage

surveff_weibull(
  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,
  variance_method = NULL,
  B = 100,
  parallel = FALSE,
  mc.cores = 2,
  seed = NULL,
  censoring_control = list(maxiter = 350),
  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).
`variance_method`	Variance estimation method: "analytical" (binary only) or "bootstrap". Default "analytical" for binary, "bootstrap" for multiple groups.
`B`	Number of bootstrap iterations. Default 100. Ignored if variance_method = "analytical".
`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 `survreg()`. Default `list(maxiter = 350)`.
`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

**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

**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 with analytical: Uses influence function approach with proper correlation structure (NOT sum of variances). - Binary with bootstrap: 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_weibull()`.
`variance_method`	Method used for variance estimation.
`boot_result`	Bootstrap results (NULL if variance_method = "analytical").