Skip to contents

Test Constant Effect (PH) Assumption for Survey Cox Models

Source: R/svycoxph_CE.R
svycoxph_CE.Rd

This function provides a valid alternative to cox.zph() for complex survey designs. It checks the Constant Effect (Proportional Hazards) assumption by splitting the follow-up time into intervals (based on event quantiles), fitting separate models for each interval, and plotting the estimated coefficients over time.

Usage

svycoxph_CE(
  formula_rhs,
  design,
  var_to_test,
  time_var = "stime",
  status_var = "status",
  n_intervals = 5,
  design_ids = NULL,
  design_weights = NULL,
  design_strata = NULL,
  verbose = FALSE,
  print_main_model = TRUE,
  print_split_summary = TRUE,
  add_smoother = FALSE,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  use_classic_theme = TRUE,
  show_null_effect = TRUE
)

Arguments

formula_rhs

A string specifying the right-hand side of the Cox model formula (e.g., "treatment + age + sex").

design

The original, un-split svydesign object.

var_to_test

A string specifying the exact coefficient name to plot (e.g., "age" or "treatmentYes").

time_var

A string for the time-to-event variable name (default "stime").

status_var

A string for the event status variable name (default "status", usually 0/1).

n_intervals

Integer. The number of time intervals to create based on event time quantiles (default is 5).

design_ids

(Optional) A formula specifying the cluster IDs (e.g., ~psu) to be used if automatic extraction fails.

design_weights

(Optional) A formula specifying the survey weights (e.g., ~weight) to be used if automatic extraction fails.

design_strata

(Optional) A formula specifying the strata (e.g., ~strata) to be used if automatic extraction fails.

verbose

Logical. If TRUE, prints debugging information about cut-points and convergence.

print_main_model

Logical. If TRUE, prints a tidy summary of the main (un-split) model.

print_split_summary

Logical. If TRUE, prints a tidy summary table of coefficients for every time interval.

add_smoother

Logical. If TRUE, adds a loess smooth line to the plot.

title

String. Custom title for the plot.

xlab

String. Custom x-axis label.

ylab

String. Custom y-axis label.

use_classic_theme

Logical. If TRUE, uses theme_classic().

show_null_effect

Logical. If TRUE, draws a dashed red line at y=0.

Value

A ggplot object showing the coefficient trend over time.

Details

Methodology: The function uses "Event-Based Splitting." Instead of splitting time into equal chunks (e.g., every 5 years), it splits time based on quantiles of the event times (e.g., 20th, 40th percentiles). This ensures that each interval contains roughly the same number of events, maintaining statistical power across all segments.

Fix for Pipe/Subset Errors: Survey design objects created via magrittr pipes or subset() often cannot be easily reconstructed. This function attempts to automatically extract the necessary design components (ids, weights, strata) and attach them to the data before splitting. If this fails, the user can manually provide the design_ids, design_weights, and design_strata arguments.

Examples

if (FALSE) { # \dontrun{
# --- 1. Load data and create a design ---
library(survey)
library(dplyr)
data(nhanes_mortality, package = "svyTable1")

# Create a base design
analytic_design <- svydesign(
  strata = ~strata,
  id = ~psu,
  weights = ~survey_weight,
  data = nhanes_mortality,
  nest = TRUE
)

# Prepare data (filter to >0 time)
data_clean <- analytic_design$variables %>%
  dplyr::filter(stime > 0) %>%
  mutate(caff_bin = ifelse(caff == "No consumption", "No", "Yes"))

# Create final design object
final_design <- svydesign(
  strata = ~strata,
  id = ~psu,
  weights = ~survey_weight,
  data = data_clean,
  nest = TRUE
)

# --- Example 1: Standard Usage ---
svycoxph_CE(
  formula_rhs = "caff_bin + age",
  design = final_design,
  var_to_test = "age",
  time_var = "stime",
  status_var = "status"
)

# --- Example 2: Manual Safety Valve (if automatic extraction fails) ---
svycoxph_CE(
  formula_rhs = "caff_bin + age",
  design = final_design,
  var_to_test = "caff_binYes", # Note: Check exact coef name
  design_ids = ~psu,
  design_weights = ~survey_weight,
  design_strata = ~strata
)
} # }