Syntax and notation

Selectors

Arguments that choose variables or columns, such as tbl_summary(include =), add_p(include =) and modify_column_hide(columns =), and the left-hand side of every formula described below, accept a selection written the way tidyselect reads it. The package implements the common forms in base R:

Names: age, "age", c(age, grade), c("age", "grade"), a character vector held in a variable, and ranges such as age:grade.
Exclusion: -trt, -c(trt, death), c(everything(), -grade).
tidyselect helpers: everything(), all_of(), any_of(), starts_with(), ends_with(), contains(), matches(), where(), last_col().
ltsummary selectors: all_continuous(), all_continuous2(), all_categorical(), all_dichotomous(), all_tests(), all_stat_cols(). See select_helpers.

The boolean operators !, & and | are not supported; use - and c() instead.

Formula and list selectors

Many arguments accept list and formula notation, e.g. tbl_summary(statistic =), tbl_summary(label =), add_p(test =) and modify_header(...). The left-hand side of a formula selects variables and the right-hand side is the value for them.

List of formulas

Typical usage is a list of formulas, where the left-hand side is a variable name or a selector.
```
tbl_summary(statistic = list(age ~ "{mean}", all_categorical() ~ "{n}"))
```
Named list

A named list is also accepted; selectors cannot be used with this syntax.
```
tbl_summary(statistic = list(age = "{mean}", response = "{n}"))
```
Hybrid named list and list of formulas

Named elements and formulas can be combined.
```
tbl_summary(statistic = list(age = "{mean}", all_categorical() ~ "{n}"))
```
Shortcuts

A single formula is equivalent to a list holding that formula.
```
tbl_summary(statistic = all_categorical() ~ "{n}")
```
To select every variable, omit the left-hand side. The two calls below are equivalent.
```
tbl_summary(statistic = ~"{n}")
tbl_summary(statistic = everything() ~ "{n}")
```

Combination selectors

Selectors can be combined with c().

tbl_summary(statistic = c(everything(), -grade) ~ "{n}")

Last one wins

When a variable is selected more than once, the last value is used, so digits = list(all_continuous() ~ 1, age ~ 2) gives age two decimal places and every other continuous variable one.

Examples

# Example 1 ----------------------------------
# selectors, names and a named list in one call
trial |>
  tbl_summary(
    include = c(age, marker, grade),
    statistic = list(all_continuous() ~ "{mean} ({sd})", grade ~ "{n} / {N}"),
    digits = list(all_continuous() ~ 1, marker ~ 2),
    label = list(age = "Age, years")
  )

# Example 2 ----------------------------------
# a one-sided formula applies to every variable
trial |>
  tbl_summary(include = c(grade, stage), statistic = ~"{p}%", digits = ~1)

# Example 3 ----------------------------------
# exclusion and ranges in `include`
trial |>
  tbl_summary(by = trt, include = c(age:grade, -marker))

Syntax and notation

Selectors

Formula and list selectors

See also

Examples