tabsurv: Comprehensive Survival Analysis Table

In R4VN: Health Data Analysis and Publication-Ready Reporting

Comprehensive Survival Analysis Table

Description

Performs descriptive survival analysis, Kaplan-Meier/Aalen-Johansen estimates, optional life tables, cumulative incidence at selected times, incidence rate, log-rank tests, Cox regression, proportional-hazards diagnostics, RMST, competing-risk Fine-Gray models, and counting-process/recurrent-event Cox models.

Usage

tabsurv(
  time,
  event,
  vars = NULL,
  by = NULL,
  data = NULL,
  failure = NULL,
  compete = NULL,
  id = NULL,
  start = NULL,
  unit = NULL,
  followup = NULL,
  km = NULL,
  lifetable = FALSE,
  at = NULL,
  risk = NULL,
  cuminc = NULL,
  rate = NULL,
  scale = 100,
  logrank = NULL,
  rr = NULL,
  rd = NULL,
  irr = NULL,
  cox = NULL,
  adjusted = NULL,
  multi = NULL,
  strata = NULL,
  cluster = NULL,
  frailty = NULL,
  finegray = NULL,
  recurrent = FALSE,
  rmst = NULL,
  tau = NULL,
  ph = NULL,
  interaction = FALSE,
  superby = NULL,
  ci = 0.95,
  digit = 2,
  p_digit = 3,
  effect_digit = 2,
  missing = FALSE,
  plot = NULL,
  title = NULL,
  show = TRUE,
  console = FALSE,
  ai = FALSE,
  ties = c("efron", "breslow", "exact"),
  report = c("auto", "brief", "full", "custom"),
  plot_args = list(),
  interpretation = FALSE,
  export = NULL,
  file = NULL,
  open = FALSE,
  strict = FALSE
)

Arguments

time	Follow-up or stop-time variable, supplied without quotes.
event	Event/status variable, supplied without quotes.
vars	Optional predictor specification created by vars().
by	Optional grouping variable for survival curves and comparisons. Hierarchical syntax is supported: in by = vars(province, sex, treatment), treatment is the innermost curve/comparison group and province > sex are ordered outer strata.
data	Optional data frame. When omitted, active R4VN data are used.
failure	Value of event representing the event of interest. For a binary event it defaults to the second factor level or larger numeric value.
compete	Optional competing-event value(s). When supplied, risk = TRUE uses the Aalen-Johansen cumulative incidence function.
id	Optional subject identifier for counting-process/recurrent data.
start	Optional start/entry time. When supplied, time is treated as stop time.
unit	Optional display unit such as "day", "month", or "year".
followup	Estimate median follow-up using reverse Kaplan-Meier when possible. With report = "auto", this is enabled unless explicitly set to FALSE.
km	Fit Kaplan-Meier (ordinary survival) or Aalen-Johansen (competing risks).
lifetable	Show a detailed life table at every observed time. The default is FALSE. For ordinary survival, the table reports numbers at risk, events, censoring, conditional survival, cumulative Kaplan-Meier survival, cumulative risk, standard error, and confidence limits. With competing risks, it reports the corresponding Aalen-Johansen event-history table and cumulative incidence.
at	Optional time points for survival/risk/rate summaries. With report = "auto" or "full", three representative follow-up times are selected automatically when at is omitted.
risk	Report cumulative risk at at. For ordinary survival this is 1-S(t); with competing risks it is the cumulative incidence function.
cuminc	Optional numeric time points at which cumulative incidence is required, for example cuminc = c(6, 12, 24). This directly activates cumulative-risk output without also requiring risk = TRUE. Ordinary survival uses 1-KM; competing-risk analysis uses the Aalen-Johansen CIF.
rate	FALSE, TRUE, "overall", "cumulative", "interval", or "all". "all" reports overall, cumulative, and interval-specific rates. The automatic profile uses the overall incidence rate.
scale	Rate multiplier, e.g. 100 for events per 100 person-time units.
logrank	Perform a log-rank test when by is supplied and no competing risk exists.
rr, rd	Compare cumulative risks between two by groups using approximate risk ratio or risk difference inference based on survival-estimate standard errors.
irr	Compare incidence rates between two by groups.
cox	Fit crude Cox models for variables in vars.
adjusted	FALSE/NULL, TRUE (adjust each focal predictor for all other focal predictors), or a vars()/character set of adjustment covariates.
multi	FALSE/NULL, TRUE (all vars in one model), or a vars()/character set defining the final multivariable Cox model.
strata	Optional stratification variable for Cox regression.
cluster	Optional clustering variable for robust Cox variance.
frailty	Optional shared-frailty variable. Do not combine with cluster.
finegray	Fit a Fine-Gray subdistribution hazards model when compete is supplied.
recurrent	FALSE/TRUE or "ag". TRUE is Andersen-Gill and requires id and start. Automatic profiles suppress ordinary KM/RMST modules for recurrent-event data unless the user explicitly requests them.
rmst	Compute restricted mean survival time.
tau	Restriction time for RMST. Defaults to the largest common curve time.
ph	Test the proportional-hazards assumption with cox.zph() for the final Cox model.
interaction	Optional vars(a, b) containing exactly two variables to include their interaction in the final multivariable Cox model.
superby	Optional outer subgroup variable retained for backward compatibility. For new code, multiple ordered outer strata can be supplied directly in by = vars(stratum1, stratum2, group).
ci	Confidence level, default 0.95.
digit, p_digit, effect_digit	Display digits.
missing	Show missing/exclusion information when printing.
plot	Draw a survival/CIF curve using gsurv() after analysis. In the automatic profiles, the plot includes confidence limits, the log-rank p-value when available, and a number-at-risk table.
title	Optional title.
show	Logical; open the formatted result in the Viewer. Default TRUE.
console	Logical; also print the traditional result in the Console. Default FALSE.
ai	Prepare a compact de-identified interpretation payload in ⁠$ai_text⁠.
ties	Cox tie method: "efron", "breslow", or "exact".
report	Reporting profile: "auto" (context-sensitive comprehensive output), "brief" (descriptive survival summary), "full" (all valid modules), or "custom" (backward-compatible concise defaults plus explicitly requested modules).
plot_args	Named list of additional arguments passed to gsurv().
interpretation	Add a cautious, deterministic interpretation table. The default is FALSE; use interpretation = TRUE when narrative output is wanted.
export	Optional export format accepted by tabexport(), such as "docx", "xlsx", or "html".
file	Optional export filename. Its extension may also determine the export format.
open	Open the exported file when supported.
strict	If TRUE, an unavailable optional module stops the analysis. The default FALSE keeps the main report and records a warning instead.

Value

An object of class r4vn_surv. Backward-compatible components are retained, with a consistent reporting contract in ⁠$descriptive⁠, ⁠$estimates⁠, ⁠$tests⁠, ⁠$diagnostics⁠, ⁠$interpretation⁠, ⁠$tables⁠, ⁠$plots⁠, ⁠$models⁠, ⁠$metadata⁠, and ⁠$call⁠.

Examples

if (requireNamespace("survival", quietly = TRUE)) {
  # Reproducible two-group data from the survival package.
  d <- survival::lung
  d$death <- as.integer(d$status == 2)
  d$group <- factor(d$sex, levels = c(1, 2),
                    labels = c("Male", "Female"))

  # 1. Complete two-group report. This includes the log-rank test.
  km <- tabsurv(
    time, death, by = group, data = d, failure = 1,
    unit = "day", at = c(90, 180, 365, 540),
    report = "auto", plot = FALSE, show = FALSE
  )
  km$logrank
  km$tests$logrank
  km$logrank$p

  
  # 2. Cumulative incidence at 6, 12, and 24 months.
  d$month <- d$time / 30.4375
  ci_month <- tabsurv(
    month, death, by = group, data = d, failure = 1,
    cuminc = c(6, 12, 24), report = "custom", show = FALSE
  )
  ci_month$cuminc

  # 3. Detailed life table and interpretation are both opt-in.
  km_detail <- tabsurv(
    time, death, by = group, data = d, failure = 1,
    at = c(90, 180, 365, 540),
    lifetable = TRUE, interpretation = TRUE, show = FALSE
  )
  head(km_detail$lifetable)
  km_detail$interpretation

  # 4. A compact KM plus log-rank analysis without automatic extras.
  km_simple <- tabsurv(
    time, death, by = group, data = d, failure = 1,
    report = "custom", km = TRUE, logrank = TRUE,
    plot = FALSE, show = FALSE
  )

  # 5. Explicit two-group effect measures and RMST.
  km_compare <- tabsurv(
    time, death, by = group, data = d, failure = 1,
    at = c(90, 180, 365, 540), risk = TRUE,
    rr = TRUE, rd = TRUE, rate = "all", irr = TRUE,
    rmst = TRUE, tau = 365, show = FALSE
  )
  km_compare$risk_compare
  km_compare$irr
  km_compare$rmst

  # 6. Publication graphs, including risk tables, are documented in ?gsurv.
  # Keeping graphics out of this example also keeps tabsurv() examples fast
  # and executable on non-interactive CRAN check devices.

  # 7. With competing risks, use the Aalen-Johansen CIF, not 1-KM.
  set.seed(2026)
  n <- 180
  t1 <- rexp(n, 0.07)
  t2 <- rexp(n, 0.05)
  tc <- runif(n, 4, 30)
  tm <- pmin(t1, t2, tc)
  dcr <- data.frame(
    time = tm,
    status = ifelse(tm == t1, 1L, ifelse(tm == t2, 2L, 0L)),
    group = factor(rep(c("A", "B"), each = n / 2))
  )
  cif <- tabsurv(
    time, status, by = group, data = dcr,
    failure = 1, compete = 2, cuminc = c(6, 12, 24),
    report = "custom", show = FALSE
  )
  cif$cuminc
  # See ?gsurv for publication CIF graphs and risk tables.
  
}

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.