fit_marginal_cox: Marginal Cox Model Estimation with Propensity Score Weighting

Description

Fits a weighted marginal Cox proportional hazards model to estimate marginal hazard ratios between treatment groups using propensity score weights. Fit Weighted Marginal Cox Model

Fits a marginal Cox model `Surv(time, event) ~ treatment` with propensity score weights to estimate marginal hazard ratios. Automatically handles zero weights (from trimming) by subsetting data before fitting.

Usage

fit_marginal_cox(
  data,
  treatment_var,
  time_var,
  event_var,
  weights,
  treatment_levels,
  reference_level,
  robust = TRUE,
  functionality = "main"
)

Value

A list containing:

cox_model: The fitted coxph model object. NULL if fitting failed in bootstrap mode.
hr_estimates: Named numeric vector of log hazard ratios (coefficients). Length = n_levels - 1. Names indicate which group is compared to reference (e.g., "trtB" means group B vs reference). Contains NA for groups that are missing in data or have no events.
hr_se_robust: Named numeric vector of robust standard errors for log HRs. Same length and names as hr_estimates. NA for failed groups.
reference_level: The treatment level used as reference.
treatment_levels: Vector of all treatment levels.
n_levels: Number of treatment levels.
n_per_group_original: Named numeric vector of sample sizes per group before trimming (from original data).
n_per_group_used: Named numeric vector of sample sizes per group actually used in Cox model (after excluding zero weights).
events_per_group_original: Named numeric vector of event counts per group before trimming.
events_per_group_used: Named numeric vector of event counts per group in fitted Cox model.

Arguments

data: A data.frame containing the complete-case analysis data.
treatment_var: A character string specifying the name of the treatment variable in data.
time_var: A character string specifying the name of the time variable in data.
event_var: A character string specifying the name of the event variable in data. Should be coded as 1 = event, 0 = censored.
weights: A numeric vector of propensity score weights with length equal to nrow(data). Returned from estimate_weights(). May contain zeros for trimmed observations (these will be excluded before fitting).
treatment_levels: A vector of unique treatment values (sorted). Should match the levels from estimate_ps().
reference_level: Which treatment level to use as reference in the Cox model. MANDATORY parameter.
robust: Logical. Use robust (sandwich) variance estimator? Default TRUE. When TRUE, uses coxph(..., robust = TRUE).
functionality: Character string indicating purpose: "main" for main point estimation or "boot" for bootstrap. Default "main". Controls error handling behavior when groups are missing or have no events.

Details

Functionality Modes:

**"main" mode (point estimation):** - If reference group is missing or has no events after trimming: throws error - If non-reference group is missing: sets its HR and SE to NA, continues - If non-reference group has no events: sets its HR and SE to NA if coxph fails - Does NOT suppress warnings/messages from coxph

**"boot" mode (bootstrap):** - If reference group is missing or has no events: returns hr_estimates with all NA, no error - If non-reference group is missing: sets its HR and SE to NA - Does NOT suppress warnings (this is handled in bootstrap wrapper function)

Model Formula: Fits Surv(time, event) ~ treatment where treatment is a factor with k levels. Cox regression automatically creates k-1 dummy variables relative to the reference level.

Zero Weights: coxph does not accept zero or negative weights. Observations with weight <= 0 are excluded before model fitting. This handles trimming automatically.

Coefficients: Coefficients represent log hazard ratios. To get hazard ratios, use exp(hr_estimates). A positive coefficient means higher hazard (worse survival) compared to reference group.

Robust Variance: When robust = TRUE, the sandwich variance estimator accounts for weighting and provides more conservative standard errors. This is recommended for propensity score weighted analyses.