Add documentation about named lists in `tbl_summary(digits)`

[ddsjoberg]

FIRST, we also need to evaluate how we can use the named lists in digits to modify the missing row stats. I think it works if the digits are all named lists (no tidy select, maybe). Minimally it may work with tidyselect, but probably not with the recycling to fill the vector length.

Once we figure out what code will and will not work, then we can update the documentation

[ddsjoberg]

Here are a few examples of using the digits argument to change the formatting of the missing stats.

I think I am only confident in urging users to pass named lists. Anything else just seems too fragile. Rather than documenting this in tbl_summary() help file, I think an example to gallery.Rmd is enough.

library(gtsummary)
packageVersion("gtsummary")
#> [1] '2.0.2.9000'

# using named lists in `digits` works for primary stats and missing stats
tbl_summary(
  trial, 
  include = c(age, response),
  missing = "always",
  missing_stat = "{N_miss} ({p_miss}%)",
  digits = list(age = list(p_miss = 2),
                response = list(p = 1, p_miss = 2))
) |> 
  as_kable()

Characteristic	N = 200
Age	47 (38, 57)
Unknown	11 (5.50%)
Tumor Response	61 (31.6%)
Unknown	7 (3.50%)

# this is a good results, but i am not sure how fragile it is
tbl_summary(
  trial, 
  include = age,
  missing = "always",
  missing_stat = "{N_miss} ({p_miss}%)",
  digits = age ~ list(2, p_miss = 2)
) |> 
  as_kable()

Characteristic	N = 200
Age	47.00 (38.00, 57.00)
Unknown	11 (5.5%)

# this is a nonsense result
tbl_summary(
  trial, 
  include = age,
  missing = "always",
  missing_stat = "{N_miss} ({p_miss}%)",
  digits = age ~ c(2, 0, 0, 4, p_miss = 2)
) |> 
  as_kable()

Characteristic	N = 200
Age	47.00 (38, 57)
Unknown	11 (5.5%)

# this is a nonsense result
tbl_summary(
  trial, 
  include = age,
  missing = "always",
  missing_stat = "{N_miss} ({p_miss}%)",
  digits = age ~ c(2, p_miss = 2, 0, 0, 4)
) |> 
  as_kable()

Characteristic	N = 200
Age	47.00 (38.00, 57)
Unknown	11 (5.5%)

^{Created on 2024-09-09 with reprex v2.1.0}