Skip to contents

Descriptive summary table with group comparisons (Table 1)

Source: R/tbl_descriptive.R
tbl_descriptive.Rd

Produces a descriptive/Table 1-style summary of a data frame, with optional group comparisons. Continuous variables are summarised as mean ± SD and compared with an independent-samples t-test (two groups) or one-way ANOVA (three or more groups). Categorical variables are summarised as n (%) and compared with a chi-squared test.

Usage

tbl_descriptive(
  data,
  group = NULL,
  vars = NULL,
  domains = list(),
  log_vars = character(0),
  digits = 2,
  p_digits = 3,
  fdr = FALSE,
  overall = TRUE,
  output = c("gt", "html", "latex")
)

Arguments

data

A data frame.

group

<tidy-select> Unquoted name of the grouping variable. If NULL (default) the overall sample is summarised without a comparison column.

vars

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

domains

A named list mapping variable names to domain/section labels, e.g. list("Metabolic" = c("hdl", "glucose"), "Anthropometric" = c("bmi", "waist")). Variables not mentioned are placed in an "Other" section.

log_vars

Character vector of variable names that were log-transformed prior to analysis. A footnote is appended noting that values are shown on the raw scale.

digits

Integer. Number of decimal places for continuous variables (default 2).

p_digits

Integer. Number of decimal places for p-values (default 3).

fdr

Logical. Apply BH FDR correction to p-values across all tests (default FALSE).

overall

Logical. Include an overall (ungrouped) column alongside group columns (default TRUE).

output

Character string specifying the render target. One of "gt" (default, for Word/PDF via gt), "html" (interactive reactable), or "latex" (LaTeX via gt::as_latex()). This value is stored on the returned object and used by clerk_render() to dispatch to the correct renderer automatically.

Value

A clerk_tbl object (a list with class "clerk_tbl") containing:

table

A data frame with one row per variable.

domains

The domain list supplied by the user.

log_vars

The log-transformed variable names.

type

Character string "descriptive".

group

Name of the grouping variable, or NULL.

output

The render target: "gt", "html", or "latex".

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")
#> Warning: invalid factor level, NA generated



  
Table 1. Sample characteristics by sex
    

      n
      Overall
      Female
      Male
      Statistic
      p
    
NA
    
age
300
46.76 ± 14.15
46.42 ± 13.63
47.35 ± 15.09
t = -0.53
5.992006e-01
waist
300
92.07 ± 11.56
92.14 ± 11.32
91.93 ± 12.03
t = 0.15
8.792922e-01
systolic_bp
300
123.25 ± 17.77
120.36 ± 17.86
128.48 ± 16.45
t = -3.97
9.521407e-05
life_satisfaction
300
18.02 ± 4.23
17.40 ± 4.25
19.14 ± 3.99
t = -3.54
4.880922e-04
Metabolic
    
hdl
300
46.81 ± 10.11
48.32 ± 9.78
44.08 ± 10.18
t = 3.50
5.599878e-04
glucose
300
91.68 ± 24.65
92.61 ± 24.49
90.01 ± 24.96
t = 0.87
3.863309e-01
bmi
300
26.15 ± 4.91
26.43 ± 4.84
25.64 ± 5.01
t = 1.32
1.895409e-01
Cognitive
    
tmt_time1
300
129.24 ± 64.98
132.81 ± 66.77
122.81 ± 61.40
t = 1.31
1.916489e-01
verbal_fluency
300
14.98 ± 4.63
15.08 ± 4.44
14.79 ± 4.97
t = 0.52
6.062013e-01
Mental health
    
bdi
300
13.64 ± 9.26
15.07 ± 8.97
11.05 ± 9.26
t = 3.65
3.325514e-04
panas_neg
300
20.98 ± 7.48
22.50 ± 7.27
18.25 ± 7.09
t = 4.92
1.662527e-06
1 Log-transformed variables shown on raw scale.