er_tte_theme: Adjust theme/labels for a time-to-event plot

In erplots: Model-Agnostic Exposure-Response Plots

Adjust theme/labels for a time-to-event plot

Description

Set axis/legend labels, plot titles/captions, axis limits, theme objects, formatters, the legend key glyph, and relative panel heights for a time-to-event plot. This does not change which variable is mapped to which aesthetic – that's the builder's job via style (see er_style_tte_curve).

Usage

er_tte_theme(
  object,
  xlab = NULL,
  ylab = NULL,
  strata_lab = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  xlim = NULL,
  ylim = NULL,
  theme_base = NULL,
  theme_extra = NULL,
  format_p = NULL,
  format_percent = NULL,
  format_number = NULL,
  draw_key = NULL,
  height_curve = NULL,
  height_risktable = NULL
)

Arguments

object	Partially constructed plot (has S3 class er_tte).
xlab	Time axis label (single string). See "Details" for why xlim (not this) drives layout decisions; xlab is purely cosmetic.
ylab	Survival-probability axis label (single string).
strata_lab	Stratification legend label (single string). Errors if stratify_by wasn't set in er_tte() – there's no stratification legend to label.
title, subtitle, caption	Plot-level annotation text (single strings).
xlim	Time-axis limits (length-2, increasing numeric vector, no NA) – overwrites object$time$limits. See "Details" for the call-order caveat.
ylim	Survival-probability axis limits (length-2, increasing numeric vector, no NA). Purely cosmetic; defaults to c(0, 1).
theme_base	A ggplot2 theme object (e.g. ggplot2::theme_minimal()) – the swappable overall visual theme, defaulting to ggplot2::theme_bw().
theme_extra	A ggplot2 theme object (e.g. from ggplot2::theme()) with additional theme tweaks layered on top of theme_base. See "Details" for its default and replacement semantics.
format_p	Formatter function (typically from scales::label_pvalue()), used by er_tte_add_summary()'s log-rank annotation.
format_percent	Formatter function (typically from scales::label_percent()), used by er_style_tte_risktable_text()'s show_percent argument to format a risk-table count as a percentage of its stratum's baseline size.
format_number	Formatter function (typically from scales::label_number()), used by er_tte_add_summary()'s er_style_tte_summary_coefficients()/er_style_tte_summary_gof() builders to format coefficient/goodness-of-fit values.
draw_key	A key-glyph function (e.g. ggplot2::draw_key_point()), passed as the curve/model layers' key_glyph argument.
height_curve, height_risktable	Relative panel heights (single positive numbers), used when er_tte_add_risktable()'s panel is stacked below the curve panel. Supplying only one leaves the other unchanged.

Details

Every argument defaults to NULL, meaning "leave whatever was set before unchanged". This allows repeated calls to er_tte_theme() to update only the supplied fields, like ggplot2::theme(). There is no implicit way to reset a field to the er_tte() default.

xlim overwrites object$time$limits directly (the same structural field er_tte() itself sets from the data), rather than a purely cosmetic ggplot2::coord_cartesian() zoom – mirroring er_plot_theme()'s own xlim (not er_vpc_theme()'s, which is display-only). This matters because object$time$limits also drives non-cosmetic defaults computed at add-layer time: er_tte_add_model()'s default time_grid and er_tte_add_risktable()'s default times both span it. Call er_tte_theme(xlim = ...) before those layers when you want the narrower/wider range reflected in their defaults; calling it after only changes the curve panel's own x-axis display. ylim, by contrast, is purely cosmetic (survival probability is always modelled on ⁠[0, 1]⁠; this only changes what's displayed), stored on object$theme$ylim and defaulting to c(0, 1).

theme_extra defaults to a panel border plus legend.position = "bottom". Supplying a new value fully replaces this default rather than merging with it, so re-include the border/legend-position settings too if you want to keep them alongside your own additions.

title/subtitle/caption are applied via a single ggplot2::labs() call on the curve panel – unlike er_plot_theme()'s patchwork::plot_annotation() indirection, this is enough even when er_tte_add_risktable()'s panel is stacked below it via patchwork::wrap_plots(), since the curve panel is always the top-most one.

Value

The input object, with the requested theme fields updated.

See Also

er_tte(), er_style_tte_curve

Examples

library(survival)
lung |>
  er_tte(time, status == 2) |>
  er_tte_add_curve() |>
  er_tte_theme(
    xlab = "Days", ylab = "Survival probability",
    title = "Overall survival"
  ) |>
  plot()

erplots documentation built on Oct. 4, 2026, 5:06 p.m.