Descriptive tables with {gtsummary}

We probably want to name the variables

tbl_summary(
  nlsy,
  by = sex_cat,
  include = c(
    sex_cat, race_eth_cat,
    region_cat, eyesight_cat,
    glasses, age_bir),
  label = list(
    race_eth_cat ~
      "Race/ethnicity",
    region_cat ~ "Region",
    eyesight_cat ~ "Eyesight",
    glasses ~ "Wears glasses",
    age_bir ~ "Age at first birth"
  ),
  missing_text = "Missing")

And do a million other things

tbl_summary(
  nlsy,
  by = sex_cat,
  include = c(
    sex_cat, race_eth_cat,
    eyesight_cat, glasses,
    age_bir),
  label = list(
    race_eth_cat ~
      "Race/ethnicity",
    eyesight_cat ~ "Eyesight",
    glasses ~ "Wears glasses",
    age_bir ~ "Age at first birth"
  ),
  missing_text = "Missing") |>
  add_p(test = list(
    all_continuous() ~ "t.test",
    all_categorical() ~
      "chisq.test")) |>
  add_overall(
    col_label = "**Total**") |>
  bold_labels() |>
  remove_footnote_header() |>
  modify_header(
    label = "**Variable**",
    p.value = "**P**") |>
  modify_caption(
    "**Participant characteristics**")

Two ways to change that table

That last example did two different kinds of customization:

tbl_summary(
  nlsy,
  by = sex_cat,
  include = c(sex_cat, race_eth_cat, age_bir),
  label = list(age_bir ~ "Age at first birth"),
  missing_text = "Missing"
) |>
  add_p() |>
  add_overall(col_label = "**Total**") |>
  bold_labels() |>
  modify_caption("**Participant characteristics**")

Some things are arguments inside tbl_summary(). Others are separate functions we piped to – and those can have arguments of their own.

What the pipe does

x |> f() is just another way of writing f(x) (or x %>% f() if you’re used to the {magrittr} pipe). So these are equivalent:

# these are the same thing
add_p(tbl_summary(nlsy, by = sex_cat))

tbl_summary(nlsy, by = sex_cat) |> add_p()

Every one of those {gtsummary} functions takes a table and returns a table. That’s why you can keep stacking them:

tbl_summary(nlsy) |> add_p() |> bold_labels() |> modify_caption("Table 1")
#          table -> table  -> table          -> table

So which one do I need?

• Argument to tbl_summary() – decisions about what the table is made of: which variables, which grouping, which statistics, what to call them. You need the data to answer these.
• A function you pipe to – things you do to a table that already exists: add a column, restyle it, caption it, export it.

The function names are a map

Once you know you want a function, the prefix tells you where to look:

Additional arguments

We saw include =, by =, label =, missing_text = in the example

statistic =:

• The default is list(all_continuous() ~ "{median} ({p25}, {p75})", all_categorical() ~ "{n} ({p}%)")
• For categorical variables, you can use {n} (frequency), {N} (denominator), {p} formatted percentage
• For continuous variables, you can use {median}, {mean}, {sd}, {var}, {min}, {max}, {sum}, ⁠{p##} (any percentile), or any function {foo}
• You can refer to individual variables with their names: list(age ~ "min = {min}; max = {max}")

Additional arguments

digits =:

• It will do its best to guess the appropriate number of digits
• Otherwise, you can pass a function:
  • digits = everything() ~ style_sigfig
• Or a value for each statistic shown
  • statistic = list(age ~ "min = {min}; max = {max}", year_of_birth = "{median} ({p25}, {p75})") :
  • digits = list(age ~ c(1, 1) year_of_birth ~ c(0, 0, 0))

Additional arguments

type =:

• One of “continuous”, “continuous2”, “categorical”, “dichotomous”
  • If a variable only has 0/1, TRUE/FALSE, or yes/no values, it will be treated as dichotomous
    • You can override this with type = list(``varname``~ "categorical")
    • Dichotomous variables only show one row (i.e., the percentage of 1’s) unless you change to categorical
      • You can change which level to show with value = list(varname ~ "level to show")
  • “continuous2” variables can have multiple rows of statistics

missing =:

• Show NA values in the table (“no”, “ifany”, “always”)

tbl_summary()

• Incredibly customizeable

  • So many options can be overwhelming
  • The FAQ/gallery is an incredible resource

• You can view it in the browser and copy/paste into Word

  • I do this more than I’d like to admit, but it’s the one step in your analysis that isn’t reproducible