Descriptive summary table with group comparisons (Table 1)

Produces a descriptive/Table 1-style summary of a data frame, with optional group comparisons. Formatting defaults are inherited from clerk_options().

Usage

tbl_descriptive(
  data,
  group = NULL,
  vars = NULL,
  domains = list(),
  log_vars = character(0),
  digits = NULL,
  p_digits = NULL,
  p_threshold = NULL,
  p_style = NULL,
  stars = NULL,
  fdr = FALSE,
  fdr_ns = NULL,
  fdr_alpha = NULL,
  domain_other = NULL,
  overall = TRUE,
  output = c("gt", "html", "latex")
)

Arguments

data

A data frame.

group

<tidy-select> Grouping variable.

vars

<tidy-select> Variables to include. Defaults to all columns except group.

domains

A named list mapping variable names to domain/section labels. An entry may itself be a named list to create a nested sub-section within a domain (e.g. repeated timepoints) – see vignette("formatting-options").

log_vars

Character vector of log-transformed variable names.

digits

Integer. Decimal places for continuous variables.

p_digits

Integer. Decimal places for p-values.

p_threshold

Numeric. P-values below this are shown as "< {threshold}". Inherits from clerk_options()$p_threshold if NULL.

p_style

Character. P-value style ("apa", "plain", "stars", "stars_p").

stars

Logical. Append significance stars.

fdr

Logical. Apply BH FDR correction (default FALSE).

fdr_ns

Logical. Replace non-surviving FDR p-values with "ns".

fdr_alpha

Numeric. Alpha level for FDR survival (BH-adjusted p).

domain_other

Character string. Label for variables not assigned to any domain. Default "" (blank). Inherits from clerk_options()$domain_other.

overall

Logical. Include an overall column (default TRUE).

output

Character string. One of "gt", "html", or "latex".

Value

A clerk_tbl object with type "descriptive".

Examples

tbl_descriptive(
  clerk_example,
  group   = sex,
  domains = list(
    "Metabolic"    = c("hdl", "glucose", "bmi"),
    "Cognitive"    = c("tmt_time", "verbal_fluency"),
    "Mental health"= c("bdi", "panas_neg")
  ),
  log_vars = "tmt_time",
  output   = "gt"
) |> clerk_render(title = "Table 1. Sample characteristics by sex")


  
Table 1. Sample characteristics by sex
    

      
n
      
Overall
      
Female
      
Male
      
Statistic
      
p
    
Metabolic
    
hdl
300
46.81 ± 10.11
48.32 ± 9.78
44.08 ± 10.18
t = 3.50
< 0.001
glucose
300
91.68 ± 24.65
92.61 ± 24.49
90.01 ± 24.96
t = 0.87
= 0.386
bmi
300
26.15 ± 4.91
26.43 ± 4.84
25.64 ± 5.01
t = 1.32
= 0.190
Cognitive
    
tmt_time1
300
129.24 ± 64.98
132.81 ± 66.77
122.81 ± 61.40
t = 1.31
= 0.192
verbal_fluency
300
14.98 ± 4.63
15.08 ± 4.44
14.79 ± 4.97
t = 0.52
= 0.606
Mental health
    
bdi
300
13.64 ± 9.26
15.07 ± 8.97
11.05 ± 9.26
t = 3.65
< 0.001
panas_neg
300
20.98 ± 7.48
22.50 ± 7.27
18.25 ± 7.09
t = 4.92
< 0.001

    
age
300
46.76 ± 14.15
46.42 ± 13.63
47.35 ± 15.09
t = -0.53
= 0.599
waist
300
92.07 ± 11.56
92.14 ± 11.32
91.93 ± 12.03
t = 0.15
= 0.879
systolic_bp
300
123.25 ± 17.77
120.36 ± 17.86
128.48 ± 16.45
t = -3.97
< 0.001
life_satisfaction
300
18.02 ± 4.23
17.40 ± 4.25
19.14 ± 3.99
t = -3.54
< 0.001
1 Log-transformed variables shown on raw scale.