Skip to main content
v2026.11,986 entries · CC-BY 4.0

survminer Cheat Sheet: ggsurvplot, ggforest and Cox Diagnostics

Version 0.5.2 survminer reference: functions by task, defaults, a worked lung example, how to read each plot and fixes for common errors.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

survminer is an R package that draws survival analysis results with ggplot2: Kaplan-Meier curves with risk tables and log-rank p-values from ggsurvplot(), hazard-ratio forest plots from ggforest(), and Cox model diagnostics from ggcoxzph() and ggcoxdiagnostics(). This cheat sheet lists the functions by task, with the arguments and defaults printed in the current documentation (version 0.5.2, published on CRAN on 2026-02-25), a worked example you can run on the lung dataset, and notes on reading each plot.

What survminer is used for in research

survminer does not fit survival models. The survival curves and Cox models come from the survival package (survfit(), coxph(), cox.zph()), and survminer turns those fitted objects into publication-style ggplot2 graphics. Its CRAN description lists survminer as a package for survival analysis and visualization, and the same CRAN entry lists survival among its imports and ggplot2 (3.4.0 or later) and ggpubr (0.1.6 or later) among its dependencies. The package maintainer is Alboukadel Kassambara, and the project site credits Marcin Kosinski and Przemyslaw Biecek as co-developers.

Researchers reach for it in four situations. The first is plotting time-to-event outcomes (overall survival, progression-free survival, time to relapse) by group, together with the number of participants still at risk. The second is presenting adjusted effects as a forest plot of hazard ratios. The third is choosing a cutpoint for a continuous marker such as a gene-expression level. The fourth is checking the proportional hazards assumption of a Cox model before reporting it. For the statistical background behind these outputs, see CASRAI’s guides to survival analysis in R, the Cox proportional hazards model and the log-rank test and its variants.

How to install or access survminer

The package is distributed on CRAN, and the project documentation gives these commands:

  1. Install the released version from CRAN: install.packages("survminer")
  2. Or install the development version from GitHub: devtools::install_github("kassambara/survminer", build_vignettes = FALSE)
  3. Load it in each session: library("survminer")

You need a working R installation first; the CASRAI guide to installing R covers that step. The CRAN page lists four vignettes: “Survival plots have never been so informative”, “Playing with fonts and texts”, “Specifying weights in log-rank comparisons” and “ggforest: show interactions and hazard ratio”. The documentation site also carries a one-page cheat sheet link in its navigation bar, alongside the function reference and articles.

survminer functions by task

The package documentation groups its functions as follows. The table below maps each task to the function that performs it.

Task Function
Plot Kaplan-Meier curves ggsurvplot()
Put several survival plots on one page arrange_ggsurvplots()
Plot cumulative events over time ggsurvevents()
Get the plotting table behind a curve surv_summary()
Find the best cutpoint for a continuous variable surv_cutpoint() and surv_categorize()
Pairwise log-rank comparisons pairwise_survdiff()
Test proportional hazards graphically ggcoxzph()
Residual diagnostics for a Cox model ggcoxdiagnostics()
Check functional form of a covariate ggcoxfunctional()
Forest plot of hazard ratios ggforest()
Adjusted survival curves from a Cox model ggcoxadjustedcurves()
Competing-risks cumulative incidence ggcompetingrisks()

The data table below lists the exact signature defaults the reference pages print for the six functions most readers use.

How to draw a Kaplan-Meier plot with survminer step by step

The package’s own example uses the lung dataset that ships with the survival package, comparing the two values of sex. Run these steps in order:

  1. Load the packages: library("survival") and library("survminer").
  2. Fit the curves with the survival package: fit <- survfit(Surv(time, status) ~ sex, data = lung).
  3. Draw the plot with a risk table, confidence bands and a p-value: ggsurvplot(fit, data = lung, palette = c("#E7B800", "#2E9FDF"), conf.int = TRUE, pval = TRUE, risk.table = TRUE, risk.table.col = "strata", legend.labs = c("Male", "Female"), risk.table.height = 0.25, xlim = c(0, 500), xlab = "Time in days", break.time.by = 100, ggtheme = theme_bw()).
  4. Add a median survival marker by setting surv.median.line = "hv", which the reference describes as drawing a horizontal and vertical line at median survival (allowed values are "none", "hv", "h" and "v").

Always pass data = explicitly. The reference says that if data is not supplied it is extracted from the fit object, but passing it avoids surprises when the fit was built inside another function.

Arguments you will change most often

The reference page documents these arguments, with the defaults stated there.

  • Colours and lines: palette accepts "hue", "grey", a brewer palette name, a custom vector such as c("blue", "red"), or a journal palette from the ggsci package such as "npg", "aaas", "lancet" or "jco". linetype accepts "strata", a numeric vector or a character vector such as c("solid", "dashed"). If you give a named palette vector, the names must match the strata names shown in the legend.
  • Uncertainty and testing: conf.int = TRUE adds confidence intervals (default FALSE). pval = TRUE adds the p-value for the comparison of curves; pval.method = TRUE adds text naming the test used. test.for.trend = TRUE returns tests for trend and needs more than two groups.
  • Tables under the plot: risk.table accepts TRUE, "absolute", "percentage", "abs_pct", "nrisk_cumcensor" or "nrisk_cumevents". cumevents = TRUE and cumcensor = TRUE add tables of cumulative events and censored observations. tables.height defaults to 0.25.
  • Axes: xlim, xlab, ylab, break.time.by, surv.scale = "percent", and xscale, where a numeric value such as 365.25 converts day labels to years, and character codes such as "d_m" convert days to months.
  • Transformations: fun = "event" plots cumulative events (1 minus survival), fun = "cumhaz" plots the cumulative hazard, and fun = "pct" shows survival as a percentage.
  • Subgroups: group.by and facet.by each take up to two grouping variables; add.all = TRUE adds the pooled curve; combine = TRUE overlays a list of fits.

Choosing a cutpoint for a continuous marker

For a continuous variable, surv_cutpoint(data, time = "time", event = "event", variables, minprop = 0.1, progressbar = TRUE) determines the optimal cutpoint using maximally selected rank statistics, computed through the maxstat package. The event column must be coded 0 and 1. The reference example uses the myeloma dataset with the variables DEPDC1, WHSC1 and CRIM1, and its summary reports cutpoints of 279.8, 3205.6 and 82.3. The workflow is three calls:

  1. res.cut <- surv_cutpoint(myeloma, time = "time", event = "event", variables = c("DEPDC1", "WHSC1", "CRIM1"))
  2. res.cat <- surv_categorize(res.cut), which returns the data with each variable split into "low" and "high" (the default labels).
  3. Fit with survfit(Surv(time, event) ~ DEPDC1, data = res.cat) and plot it with ggsurvplot().

minprop = 0.1 is the minimum proportion of observations allowed in a group. Treat a data-driven cutpoint as a modelling choice that must be reported, because the threshold was selected using the same outcome data it is then used to compare.

Forest plots and Cox diagnostics

ggforest(model, data = NULL, main = "Hazard ratio", cpositions = c(0.02, 0.22, 0.4), fontsize = 0.7, refLabel = "reference", noDigits = 2) requires a coxph model. The reference examples use the colon dataset: coxph(Surv(time, status) ~ sex + rx + adhere, data = colon). For a proportional hazards check, run cox.zph() on a fitted model and pass the result to ggcoxzph(); the reference example fits coxph(Surv(futime, fustat) ~ age + ecog.ps + rx) on the ovarian data, then calls ggcoxzph(cox.zph.fit, var = c("ecog.ps", "rx")) to show only those two covariates. For residual plots, ggcoxdiagnostics(fit, type = "deviance") accepts the types "martingale", "deviance", "score", "schoenfeld", "dfbeta", "dfbetas", "scaledsch" and "partial".

How to read the output

A ggsurvplot() result has up to three parts, and the value it returns is a list with named components: plot (the survival plot as a ggplot object), table (the number-at-risk table), cumevents, ncensor.plot, data.survplot and data.survtable. Because the plot is a ggplot object, you can add layers to $plot and extract the underlying data frames for a supplementary table. For general guidance on the curve itself, read how to read a Kaplan-Meier curve.

  • Step curves: each curve shows the estimated survival probability over time for one stratum. Where a median line is requested, the vertical line marks the time at which the curve crosses 0.5.
  • Confidence bands: shaded areas appear only with conf.int = TRUE. Bands that widen late in follow-up reflect the shrinking number of people still at risk, which you can confirm in the risk table.
  • The p-value: it tests the difference between curves, and pval.method = TRUE prints which test was used, so you can state it in the figure legend.
  • Forest plot: each row is a covariate level with its hazard ratio and confidence interval; the label given by refLabel marks the reference level. See how to interpret a hazard ratio for what a ratio above or below 1 means.
  • Schoenfeld plots from ggcoxzph(): the function plots the cox.zph result covariate by covariate, with residual points and a standard-error band on by default (resid = TRUE, se = TRUE; smoothing defaults df = 4 and nsmo = 40). A smooth line that trends with time rather than staying flat is the pattern that questions the proportional hazards assumption for that covariate.
  • Deviance and martingale residuals from ggcoxdiagnostics(): the function adds a dashed horizontal line at zero (hline = TRUE) and a smoothed line (sline = TRUE) to show the local average of the residuals.

Troubleshooting survminer

  • Warning from ggforest() about missing data: data defaults to NULL and the function warns when it is omitted. Pass the same data frame you used in coxph().
  • Wrong model class: ggforest() needs a coxph model and ggcoxzph() needs the output of cox.zph(), not the model itself. Passing the model where the test result is expected, or the reverse, fails.
  • Event coding in surv_cutpoint(): the event variable must be 0/1. Recode a factor with, for example, “dead” and “alive” levels before calling it.
  • Colours assigned to the wrong group: the first palette colour goes to the first factor level unless you pass a named vector whose names match the legend strata labels. Likewise, legend.labs must be given in the same order as the strata.
  • Warning from ggcoxdiagnostics() about ox.scale: the documentation’s own example output shows that ox.scale = "time" works only with type = "schoenfeld" or "scaledsch". The linear.predictions argument is deprecated in favour of ox.scale.
  • Old code from older cheat sheets: some third-party copies of the cheat sheet describe version 0.4.9. Check the current reference pages for the function name and arguments before reusing old code. For example, the current index lists ggcoxadjustedcurves() for adjusted curves.
  • Installation fails on dependencies: survminer depends on ggplot2 3.4.0 or later and ggpubr 0.1.6 or later, so update those first if install.packages() reports a version conflict.

Free alternatives to survminer

survminer is free and open source on CRAN. A comparable CRAN package for time-to-event figures is ggsurvfit. The facts below are from each package’s CRAN page.

Package CRAN version Published Described as Notable requirement
survminer 0.5.2 2026-02-25 Survival analysis and visualization, built on ggplot2 and ggpubr ggplot2 3.4.0 or later, ggpubr 0.1.6 or later
ggsurvfit 1.2.1 2026-07-24 Time-to-event figures written as ggplot2 geoms and stat methods that combine with other ggplot2 functions R 4.1 or later, ggplot2 4.0.0 or later

Which package fits depends on your workflow. survminer bundles the risk table, the p-value and the Cox diagnostics in single function calls, while ggsurvfit describes a modular design in which each element is added with ggplot2 syntax. Base R and the survival package can also plot a survfit object directly, without either extension.

Sources

Data: survminer function signatures and key defaults (version 0.5.2)

Compares the six most-used survminer functions by required input object, default value of selected arguments and the example dataset used in the official reference pages. Compiled from the CRAN page and the pkgdown reference pages for version 0.5.2, read 2026-11-17.

Period covered: 2026.

survminer function signatures and key defaults (version 0.5.2)
FunctionRequired inputSelected defaultsOfficial example dataset
ggsurvplotsurvfit object (data optional, extracted from fit if missing)conf.int = FALSE; pval = FALSE; risk.table = FALSE; surv.median.line = 'none'; tables.height = 0.25lung (package home page)
ggforestcoxph modeldata = NULL; main = 'Hazard ratio'; fontsize = 0.7; refLabel = 'reference'; noDigits = 2colon
surv_cutpointdata frame with time, event (0/1) and variablesminprop = 0.1; progressbar = TRUE; method: maximally selected rank statistics (maxstat)myeloma
surv_categorizesurv_cutpoint resultlabels = c('low', 'high')myeloma
ggcoxzphcox.zph objectresid = TRUE; se = TRUE; df = 4; nsmo = 40; point.col = 'red'ovarian
ggcoxdiagnosticscoxph modeltype = one of 8 residual types (martingale, deviance, score, schoenfeld, dfbeta, dfbetas, scaledsch, partial); hline = TRUE; sline = TRUEovarian

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about survminer Cheat Sheet: ggsurvplot, ggforest and Cox Diagnostics

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →