Add ESS Table Header

This function replaces the counts in the default header of gtsummary::tbl_svysummary() tables to counts representing the Effective Sample Size (ESS). See ess() for details.

Usage

add_ess_header(
  x,
  header = "**{level}**  \nESS = {format(n, digits = 1, nsmall = 1)}"
)

Arguments

x

(tbl_svysummary)
Object of class 'tbl_svysummary' typically created with gtsummary::tbl_svysummary().

header

(string)
String specifying updated header. Review gtsummary::modify_header() for details on use.

Value

a 'gtsummary' table

Details

The header statistics available to header are the ESS of the column (n), the total the columns are a share of (N), and that share (p). ESS is not additive, so the ESS of the whole sample is not the total that the group ESS values divide up. For a table with a gtsummary::tbl_svysummary(by =) variable, N is therefore the sum of the group ESS values and p is each group's share of that sum, whether or not the table also has an overall column from gtsummary::add_overall(). The overall column reports the ESS of the whole sample as both n and N, so its p is 1.

Examples

svy <- survey::svydesign(~1, data = nhefs_weights, weights = ~ w_ate)

gtsummary::tbl_svysummary(svy, include = c(age, sex, smokeyrs)) |>
  add_ess_header()


  
Characteristic
      
Overall

ESS = 1013.31
    
AGE IN 1971
43 (33, 53)
0: MALE 1: FEMALE

    0
1,527 (49%)
    1
1,599 (51%)
YEARS OF SMOKING
24 (14, 33)
1 Median (Q1, Q3); n (%)
    
Abbreviation: ESS = Effective Sample Size
    
hdr <- paste0(
  "**{level}**  \n",
  "N = {n_unweighted}; ESS = {format(n, digits = 1, nsmall = 1)}"
)
gtsummary::tbl_svysummary(svy, by = qsmk, include = c(age, sex, smokeyrs)) |>
  add_ess_header(header = hdr)


  
Characteristic
      
0

N = 1163; ESS = 1128.61
      
1

N = 403; ESS = 326.01
    
AGE IN 1971
43 (33, 52)
43 (33, 53)
0: MALE 1: FEMALE



    0
764 (49%)
764 (49%)
    1
802 (51%)
797 (51%)
YEARS OF SMOKING
24 (15, 33)
24 (14, 33)
1 Median (Q1, Q3); n (%)
    
Abbreviation: ESS = Effective Sample Size