Many manuscript figures are paired with a small numeric table: a numbers-at-risk strip below a Kaplan-Meier curve, or the count panel beneath a longitudinal participation bar chart. The hvtiPlotR plot objects carry these companion tables alongside the plot data, so we can pull the numbers straight out and render them with gt (Iannone et al. 2026), the right tool, as in the publication tables chapter, when a table’s destination is this book or another HTML document. Manuscript tables headed for a Word file go through hvtiRtables instead, which turns a gtsummary summary into a CORR-compliant flat-header table.
A figure shows the shape of a result; the companion table gives the reader the numbers the shape rests on. The two go together when a curve hides how much data backs each region of it. The clearest case is the numbers-at-risk strip beneath a Kaplan-Meier curve: the curve might look confident out at ten years, but if only eight patients remain at risk there, the at-risk row is what tells the reader to read that tail with caution. Reach for a companion table whenever the figure invites a question the plot cannot answer on its own (“based on how many?”) and you want the answer on the same page rather than buried in the text.
The at-risk count is a denominator, not a second estimate. At time \(t\) it counts patients who are still observed and event-free immediately before \(t\). An event changes the survival curve and removes that patient from later risk sets; censoring removes a patient from later risk sets without creating a survival step. Thus the count tells you how much information supports \(S(t)\) and its confidence interval, but it does not tell you the survival probability by itself.
We work through two cases the package already supports: the at-risk strip that a survival curve needs beside it, and the participation counts that sit beneath a longitudinal bar chart. In both, the numbers already live on the plot object, so we never recompute them and risk a table that disagrees with its own figure.
hv_survival() stores its companion tables in the object’s $tables slot. The numbers-at-risk strip lives in $tables$risk (one row per strata × report-time) and the per-time-point summary in $tables$report.
km <- hv_survival(
sample_survival_data(n = 500, seed = 42),
report_times = seq(0, 20, 5)
)
names(km$tables)[1] "risk" "report"km$tables$risk strata report_time n.risk
1 All 0 500
2 All 5 411
3 All 10 321
4 All 15 259
5 All 20 207We render the at-risk table directly with gt, relabelling the columns for presentation.
km$tables$risk |>
gt() |>
tab_header(
title = "Numbers at Risk",
subtitle = "Patients remaining under follow-up at each report time"
) |>
cols_label(
strata = "Stratum",
report_time = "Time (years)",
n.risk = "At risk (n)"
)| Numbers at Risk | ||
| Patients remaining under follow-up at each report time | ||
| Stratum | Time (years) | At risk (n) |
|---|---|---|
| All | 0 | 500 |
| All | 5 | 411 |
| All | 10 | 321 |
| All | 15 | 259 |
| All | 20 | 207 |
The companion report table carries the survival estimates and confidence limits at the same report times. It lets you quote a 5- or 10-year estimate together with the denominator that supports it.
km$tables$report |>
gt() |>
tab_header(title = "Survival Estimates at Report Times") |>
cols_label(
strata = "Stratum",
report_time = "Time (years)",
surv = "S(t)",
lower = "95% LCL",
upper = "95% UCL",
n.risk = "At risk",
n.event = "Events"
) |>
fmt_number(columns = c(surv, lower, upper), decimals = 3)| Survival Estimates at Report Times | ||||||
| Stratum | Time (years) | S(t) | 95% LCL | 95% UCL | At risk | Events |
|---|---|---|---|---|---|---|
| All | 0 | 1.000 | 1.000 | 1.000 | 500 | 0 |
| All | 5 | 0.822 | 0.786 | 0.853 | 412 | 1 |
| All | 10 | 0.642 | 0.599 | 0.683 | 322 | 1 |
| All | 15 | 0.518 | 0.474 | 0.562 | 260 | 1 |
| All | 20 | 0.414 | 0.372 | 0.458 | 207 | 0 |
For the figure itself, build the curve and the risk panel from that same km object. hv_atrisk_compose() reads the finished curve’s x-range and applies it to the table, so the 0-, 5-, 10-, 15-, and 20-year counts sit directly beneath their curve positions. This is why the report times and axis breaks are set to the same sequence.
km_curve <- plot(km) +
scale_color_manual(values = c(All = "steelblue"), guide = "none") +
scale_fill_manual(values = c(All = "steelblue"), guide = "none") +
scale_x_continuous(breaks = seq(0, 20, 5)) +
scale_y_continuous(breaks = seq(0, 100, 20),
labels = function(x) paste0(x, "%")) +
coord_cartesian(xlim = c(0, 20), ylim = c(0, 100)) +
labs(x = "Years after operation", y = "Freedom from death (%)") +
theme_hv_manuscript()
km_risk <- hv_atrisk(km)
hv_atrisk_compose(km_curve, km_risk)
hv_longitudinal() produces a two-panel figure: a grouped bar chart of participation counts and a numeric table panel below it. The underlying counts live in the object’s $data slot in long format (one row per time-window × series), with the column roles recorded in $meta.
lc <- hv_longitudinal(sample_longitudinal_counts_data(n_patients = 300, seed = 42L))
names(lc)[1] "data" "meta" "tables"lc$meta[c("x_col", "group_col", "count_col")]$x_col
[1] "time_label"
$group_col
[1] "series"
$count_col
[1] "count"str(lc$data)'data.frame': 14 obs. of 3 variables:
$ time_label: Factor w/ 7 levels "≥0 Days","≥1 Month",..: 1 2 3 4 5 6 7 1 2 3 ...
$ series : chr "Patients" "Patients" "Patients" "Patients" ...
$ count : int 19 47 49 100 159 101 276 19 50 56 ...We reshape the long counts into a wide table (one row per follow-up window, one column per series) and render it with gt. This is the tabular companion to the bar chart’s table panel.
lc_wide <- lc$data |>
tidyr::pivot_wider(
names_from = series,
values_from = count
)
lc_wide# A tibble: 7 × 3
time_label Patients Measurements
<fct> <int> <int>
1 ≥0 Days 19 19
2 ≥1 Month 47 50
3 ≥3 Months 49 56
4 ≥6 Months 100 118
5 ≥1 Year 159 217
6 ≥2 Years 101 113
7 ≥2.5 Years 276 620lc_wide |>
gt(rowname_col = "time_label") |>
tab_header(
title = "Longitudinal Participation Counts",
subtitle = "Patients and measurements at each follow-up window"
) |>
fmt_number(columns = where(is.numeric), decimals = 0) |>
tab_stubhead(label = "Follow-up window")| Longitudinal Participation Counts | ||
| Patients and measurements at each follow-up window | ||
| Follow-up window | Patients | Measurements |
|---|---|---|
| ≥0 Days | 19 | 19 |
| ≥1 Month | 47 | 50 |
| ≥3 Months | 49 | 56 |
| ≥6 Months | 100 | 118 |
| ≥1 Year | 159 | 217 |
| ≥2 Years | 101 | 113 |
| ≥2.5 Years | 276 | 620 |
The gt version above is for a standalone table, say in the manuscript body or a supplement. When the numbers belong inside the figure, the package draws them as a table panel you stack under the chart. For reference, the same counts rendered as the in-figure table panel appear below the bar chart when the two are composed with patchwork. Building both from the same lc$data keeps the standalone table and the in-figure panel telling one story.
p_bar <- plot(lc) +
scale_fill_manual(
values = c(Patients = "steelblue", Measurements = "firebrick"),
name = NULL
) +
labs(x = NULL, y = "Count (n)")
p_tbl <- plot(lc, type = "table") +
scale_colour_manual(
values = c(Patients = "steelblue", Measurements = "firebrick"),
guide = "none"
)
p_bar / p_tbl + plot_layout(heights = c(3, 1))
report_times explicitly when you build km, use those times as the curve’s breaks, and let hv_atrisk_compose() align the finished panels. If you later crop the curve, inspect the table again.