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:
- Install the released version from CRAN:
install.packages("survminer") - Or install the development version from GitHub:
devtools::install_github("kassambara/survminer", build_vignettes = FALSE) - 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:
- Load the packages:
library("survival")andlibrary("survminer"). - Fit the curves with the survival package:
fit <- survfit(Surv(time, status) ~ sex, data = lung). - 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()). - 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:
paletteaccepts"hue","grey", a brewer palette name, a custom vector such asc("blue", "red"), or a journal palette from the ggsci package such as"npg","aaas","lancet"or"jco".linetypeaccepts"strata", a numeric vector or a character vector such asc("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 = TRUEadds confidence intervals (defaultFALSE).pval = TRUEadds the p-value for the comparison of curves;pval.method = TRUEadds text naming the test used.test.for.trend = TRUEreturns tests for trend and needs more than two groups. - Tables under the plot:
risk.tableacceptsTRUE,"absolute","percentage","abs_pct","nrisk_cumcensor"or"nrisk_cumevents".cumevents = TRUEandcumcensor = TRUEadd tables of cumulative events and censored observations.tables.heightdefaults to 0.25. - Axes:
xlim,xlab,ylab,break.time.by,surv.scale = "percent", andxscale, 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, andfun = "pct"shows survival as a percentage. - Subgroups:
group.byandfacet.byeach take up to two grouping variables;add.all = TRUEadds the pooled curve;combine = TRUEoverlays 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:
res.cut <- surv_cutpoint(myeloma, time = "time", event = "event", variables = c("DEPDC1", "WHSC1", "CRIM1"))res.cat <- surv_categorize(res.cut), which returns the data with each variable split into"low"and"high"(the defaultlabels).- Fit with
survfit(Surv(time, event) ~ DEPDC1, data = res.cat)and plot it withggsurvplot().
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 = TRUEprints 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
refLabelmarks 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 thecox.zphresult covariate by covariate, with residual points and a standard-error band on by default (resid = TRUE,se = TRUE; smoothing defaultsdf = 4andnsmo = 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:datadefaults toNULLand the function warns when it is omitted. Pass the same data frame you used incoxph(). - Wrong model class:
ggforest()needs acoxphmodel andggcoxzph()needs the output ofcox.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.labsmust be given in the same order as the strata. - Warning from
ggcoxdiagnostics()aboutox.scale: the documentation’s own example output shows thatox.scale = "time"works only withtype = "schoenfeld"or"scaledsch". Thelinear.predictionsargument is deprecated in favour ofox.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
- CRAN: Package survminer, checked 2026-11-17
- survminer documentation: Drawing Survival Curves using ggplot2, checked 2026-11-17
- survminer reference: ggsurvplot, checked 2026-11-17
- survminer reference: ggforest, checked 2026-11-17
- survminer reference: surv_cutpoint, checked 2026-11-17
- survminer reference: ggcoxzph, checked 2026-11-17
- survminer reference: ggcoxdiagnostics, checked 2026-11-17
- CRAN: Package ggsurvfit, checked 2026-11-17
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.
| Function | Required input | Selected defaults | Official example dataset |
|---|---|---|---|
| ggsurvplot | survfit object (data optional, extracted from fit if missing) | conf.int = FALSE; pval = FALSE; risk.table = FALSE; surv.median.line = 'none'; tables.height = 0.25 | lung (package home page) |
| ggforest | coxph model | data = NULL; main = 'Hazard ratio'; fontsize = 0.7; refLabel = 'reference'; noDigits = 2 | colon |
| surv_cutpoint | data frame with time, event (0/1) and variables | minprop = 0.1; progressbar = TRUE; method: maximally selected rank statistics (maxstat) | myeloma |
| surv_categorize | surv_cutpoint result | labels = c('low', 'high') | myeloma |
| ggcoxzph | cox.zph object | resid = TRUE; se = TRUE; df = 4; nsmo = 40; point.col = 'red' | ovarian |
| ggcoxdiagnostics | coxph model | type = one of 8 residual types (martingale, deviance, score, schoenfeld, dfbeta, dfbetas, scaledsch, partial); hline = TRUE; sline = TRUE | ovarian |
Sources
- CRAN: Package survminer (accessed 2026-11-17)
- survminer reference: ggsurvplot (accessed 2026-11-17)
- survminer reference: ggforest (accessed 2026-11-17)
- survminer reference: surv_cutpoint (accessed 2026-11-17)
- survminer reference: ggcoxzph (accessed 2026-11-17)
- survminer reference: ggcoxdiagnostics (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







