Add digits argument to h_tbl_median_surv and control_surv_med_annot

Expose digits parameter (default 4) to control signif() precision
for median survival time and CI values in the annotation table.
The parameter is passed through from g_km() via control_annot_surv_med.

Author: Melkiades

NEWS.md

@@ -6,6 +6,7 @@
 ### Enhancements
 * Added `alternative` argument to `s_coxph_pairwise()` to allow one-sided hypothesis testing. 
 * Added `lr_stat_df` to the parameters return list of `s_coxph_pairwise()`.
+* Added `digits` argument to `h_tbl_median_surv()` and `control_surv_med_annot()` to control significant digits for median survival annotation. (#1467)
 
 # tern 0.9.10
 

R/g_km.R

@@ -536,7 +536,11 @@ g_km <- function(df,
 
   # add median survival time annotation table
   if (annot_surv_med) {
-    surv_med_tbl <- h_tbl_median_surv(fit_km = fit_km, armval = armval)
+    surv_med_tbl <- h_tbl_median_surv(
+      fit_km = fit_km,
+      armval = armval,
+      digits = control_annot_surv_med[["digits"]] %||% 4
+    )
     bg_fill <- if (isTRUE(control_annot_surv_med[["fill"]])) "#00000020" else control_annot_surv_med[["fill"]]
 
     gg_surv_med <- df2gg(surv_med_tbl, font_size = font_size, colwidths = c(1, 1, 2), bg_fill = bg_fill) +

R/h_km.R

@@ -23,17 +23,22 @@ NULL
 #'   table can be added in [g_km()] by setting `annot_surv_med=TRUE`, and can be configured using the
 #'   `control_surv_med_annot()` function by setting it as the `control_annot_surv_med` argument.
 #'
+#' @param digits (`integer(1)`)\cr number of significant digits for median survival
+#'   time and confidence interval values. Defaults to `4`.
+#'
 #' @examples
 #' control_surv_med_annot()
+#' control_surv_med_annot(digits = 2)
 #'
 #' @export
-control_surv_med_annot <- function(x = 0.8, y = 0.85, w = 0.32, h = 0.16, fill = TRUE) {
+control_surv_med_annot <- function(x = 0.8, y = 0.85, w = 0.32, h = 0.16, fill = TRUE, digits = 4) {
   assert_proportion_value(x)
   assert_proportion_value(y)
   assert_proportion_value(w)
   assert_proportion_value(h)
+  checkmate::assert_int(digits, lower = 1)
 
-  list(x = x, y = y, w = w, h = h, fill = fill)
+  list(x = x, y = y, w = w, h = h, fill = fill, digits = digits)
 }
 
 #' @describeIn control_annot Control function for formatting the Cox-PH annotation table. This annotation table can be
@@ -117,6 +122,8 @@ h_xticks <- function(data, xticks = NULL, max_time = NULL) {
 #' Transform a survival fit to a table with groups in rows characterized by N, median and confidence interval.
 #'
 #' @inheritParams h_data_plot
+#' @param digits (`integer(1)`)\cr number of significant digits for median and CI values.
+#'   Defaults to `4`.
 #'
 #' @return A summary table with statistics `N`, `Median`, and `XX% CI` (`XX` taken from `fit_km`).
 #'
@@ -130,9 +137,11 @@ h_xticks <- function(data, xticks = NULL, max_time = NULL) {
 #'   data = adtte
 #' )
 #' h_tbl_median_surv(fit_km = fit)
+#' h_tbl_median_surv(fit_km = fit, digits = 2)
 #'
 #' @export
-h_tbl_median_surv <- function(fit_km, armval = "All") {
+h_tbl_median_surv <- function(fit_km, armval = "All", digits = 4) {
+  checkmate::assert_int(digits, lower = 1)
   y <- if (is.null(fit_km$strata)) {
     as.data.frame(t(summary(fit_km)$table), row.names = armval)
   } else {
@@ -143,9 +152,9 @@ h_tbl_median_surv <- function(fit_km, armval = "All") {
   }
   conf.int <- summary(fit_km)$conf.int # nolint
   y$records <- round(y$records)
-  y$median <- signif(y$median, 4)
+  y$median <- signif(y$median, digits)
   y$`CI` <- paste0(
-    "(", signif(y[[paste0(conf.int, "LCL")]], 4), ", ", signif(y[[paste0(conf.int, "UCL")]], 4), ")"
+    "(", signif(y[[paste0(conf.int, "LCL")]], digits), ", ", signif(y[[paste0(conf.int, "UCL")]], digits), ")"
   )
   stats::setNames(
     y[c("records", "median", "CI")],

man/control_annot.Rd

@@ -18,6 +18,33 @@
       $fill
       [1] TRUE
       
+      $digits
+      [1] 4
+      
+
+# control_surv_med_annot works with custom digits
+
+    Code
+      res
+    Output
+      $x
+      [1] 0.8
+      
+      $y
+      [1] 0.85
+      
+      $w
+      [1] 0.32
+      
+      $h
+      [1] 0.16
+      
+      $fill
+      [1] TRUE
+      
+      $digits
+      [1] 2
+      
 
 # control_coxph_annot works with default settings
 
@@ -39,6 +66,9 @@
       $fill
       [1] TRUE
       
+      $digits
+      [1] 4
+      
       $ref_lbls
       [1] FALSE
       
@@ -98,6 +128,16 @@
       ARM B 73  727.8 (555.8, 1156)
       ARM C 58  632.3   (393, 1001)
 
+# h_tbl_median_surv respects digits parameter
+
+    Code
+      res
+    Output
+             N Median      95% CI
+      ARM A 69    970 (690, 1600)
+      ARM B 73    730 (560, 1200)
+      ARM C 58    630 (390, 1000)
+
 # h_tbl_coxph_pairwise estimates HR, CI and pvalue
 
     Code

man/h_tbl_median_surv.Rd

@@ -11,6 +11,13 @@ testthat::test_that("control_surv_med_annot works with default settings", {
   testthat::expect_snapshot(res)
 })
 
+testthat::test_that("control_surv_med_annot works with custom digits", {
+  result <- control_surv_med_annot(digits = 2)
+
+  res <- testthat::expect_silent(result)
+  testthat::expect_snapshot(res)
+})
+
 testthat::test_that("control_coxph_annot works with default settings", {
   result <- control_coxph_annot()
 
@@ -84,6 +91,13 @@ testthat::test_that("h_tbl_median_surv estimates median survival time with CI",
   testthat::expect_snapshot(res)
 })
 
+testthat::test_that("h_tbl_median_surv respects digits parameter", {
+  result <- h_tbl_median_surv(fit_km = test_fit, digits = 2)
+
+  res <- testthat::expect_silent(result)
+  testthat::expect_snapshot(res)
+})
+
 testthat::test_that("h_tbl_coxph_pairwise estimates HR, CI and pvalue", {
   df <- tern_ex_adtte %>%
     filter(PARAMCD == "OS") %>%