gsurv: Survival and Cumulative Incidence Curves

In R4VN: Health Data Analysis and Publication-Ready Reporting

Survival and Cumulative Incidence Curves

Description

Draws Kaplan-Meier survival, cumulative risk, or competing-risk cumulative incidence curves from a tabsurv() result. Uses the existing R4VN base-graphics engine and can add confidence intervals, censor marks, log-rank p-values, median lines, and number-at-risk tables. Examples below are self-contained.

Usage

gsurv(
  x,
  type = NULL,
  xlab = NULL,
  ylab = NULL,
  xtitle = NULL,
  ytitle = NULL,
  xlim = NULL,
  ylim = NULL,
  breaks = NULL,
  percent = TRUE,
  ci = FALSE,
  censor = TRUE,
  color = NULL,
  palette = "default",
  linetype = NULL,
  line_width = 1.5,
  ci_color = NULL,
  ci_alpha = 0.45,
  ci_linetype = 3,
  ci_line_width = NULL,
  censor_color = NULL,
  censor_pch = 3,
  censor_size = 0.7,
  median_color = "gray50",
  median_lty = 2,
  median_lwd = 1,
  ref_color = "gray55",
  ref_lty = 3,
  ref_lwd = 1,
  size = 11,
  labels = NULL,
  legend = TRUE,
  legend_position = "topright",
  pvalue = FALSE,
  median = FALSE,
  risk_table = FALSE,
  risk_at = NULL,
  xline = NULL,
  yline = NULL,
  title = NULL,
  subtitle = NULL,
  note = NULL,
  theme = "journal",
  file = NULL,
  width = 7,
  height = NULL,
  dpi = 300,
  show = TRUE,
  bg = "white",
  vline = NULL,
  hline = NULL
)

Arguments

x	An object returned by tabsurv().
type	NULL, "survival", "risk", or "cif". NULL chooses automatically.
xlab, ylab	Axis titles retained for convenience.
xtitle, ytitle	R4VN-style aliases for the x- and y-axis titles; when supplied they override xlab/ylab.
xlim, ylim	Optional axis limits.
breaks	Numeric spacing between x ticks, or explicit x tick positions.
percent	Show y values as percentages.
ci	Show confidence limits.
censor	Show censor marks for ordinary Kaplan-Meier curves.
color, palette	Curve colors; compatible with other R4VN graphs.
linetype	Line types, recycled across groups.
line_width	Curve line width.
ci_color, ci_alpha, ci_linetype, ci_line_width	Confidence-limit colour, transparency, line type, and line width. ci_color = NULL follows each curve colour.
censor_color, censor_pch, censor_size	Censor-mark colour, point symbol, and size. censor_color = NULL follows each curve colour.
median_color, median_lty, median_lwd	Colour, line type, and width for median-survival reference lines.
ref_color, ref_lty, ref_lwd	Colour, line type, and width for user-specified xline/yline reference lines.
size	Base text size, consistent with other R4VN graph functions.
labels	Optional replacement labels for curve groups.
legend	TRUE/FALSE or a character legend title.
legend_position	Base graphics legend position.
pvalue	Annotate the log-rank p-value when available.
median	Draw median-survival reference lines.
risk_table	Add number-at-risk table below the plot.
risk_at	Time points for the risk table. Defaults to plot ticks or tabsurv(at=).
xline, yline	Optional reference lines at x- and y-axis values.
title, subtitle, note	Plot annotations.
theme, file, width, height, dpi, show, bg	Graph-output controls.
vline, hline	Deprecated aliases for xline and yline.

Value

An r4vn_graph object.

Examples

if (requireNamespace("survival", quietly = TRUE)) {
  d <- data.frame(
    time = c(5, 8, 10, 12, 15, 18, 20, 22),
    event = c(1, 0, 1, 1, 0, 1, 0, 1),
    group = factor(rep(c("A", "B"), 4))
  )
  s <- tabsurv(time, event, by = group, data = d, km = TRUE, show = FALSE)
  gsurv(s, show = FALSE)
  gsurv(s, type = "risk", ci = TRUE, pvalue = TRUE, show = FALSE)
  gsurv(s, risk_table = TRUE, risk_at = c(0, 10, 20), show = FALSE)
}

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