vars: Specify Variables for R4VN Tables

In R4VN: Health Data Analysis and Publication-Ready Reporting

Specify Variables for R4VN Tables

Description

Captures variable specifications without evaluating them immediately. Prefixes determine how variables are summarized and which observed categorical level is used as the model reference category. The i. prefix is accepted as an explicit categorical declaration so the same syntax can be reused in regression and survival commands.

Usage

vars(...)

Arguments

...	One or more unquoted variable specifications or selectors. Examples include sex, i.sex, b2.age_group, c.age, q.weight, f.gestational_age, ., `kt*`, `*score`, `*kt*`, and vars(., -id).

Details

The function also supports deferred selectors: . for all variables, wildcard selectors using *, and exclusions using unary -. Deferred selectors are expanded only after the calling analysis function knows which data frame is being used.

Supported prefixes are:

• no prefix: automatic typing from the data. Numeric/integer variables use mean and standard deviation; factor/character/logical variables are categorical using their first observed level as reference;

• i.: force categorical treatment and use the first observed level as reference. This is equivalent to b1. and makes vars(i.sex) consistent with regression-model syntax;

• b1., b2., b3., ...: force categorical treatment and use the first, second, third, or corresponding observed level as reference;

• c.: numeric variable summarized by mean and standard deviation;

• q.: numeric variable summarized by median and interquartile range;

• f.: numeric variable summarized by mean, median, and range.

Selector syntax:

• vars(.): select all variables intentionally;

• vars(`kt*`): names beginning with kt;

• vars(`*kt`): names ending with kt;

• vars(`*kt*`): names containing kt;

• vars(., -id): all variables except id;

• vars(`kt*`, -kt_total): wildcard selection except kt_total;

• vars(., -`id*`): all variables except names beginning with id.

Because * is an R operator, wildcard specifications must be written inside backticks. Thus use vars(`kt*`), not vars(kt*). A selector consisting only of asterisks is deliberately rejected; use vars(.) when all variables are intended.

Prefixes can be combined with wildcard selectors, for example vars(`c.lab*`), vars(`q.score*`), or vars(`b2.item*`).

Exact specifications are more specific than wildcard specifications, and wildcard specifications are more specific than .. Therefore an exact specification can override a broader selector. For example, vars(`c.lab*`, q.lab_crp) declares all lab* variables as mean/SD except lab_crp, which is median/IQR. When two selectors have the same specificity, the later one wins. Exclusions are applied last and always win.

Unprefixed variables and deferred selectors such as . and `kt*` are stored with type "default" until they are resolved against a data frame. With default_type = "auto" in .r4vn_resolve_vars(), factor/character/logical columns become categorical and numeric/integer columns become mean/SD variables. Use an explicit b1., b2., ... prefix when a numeric-coded variable should be treated as categorical instead.

Prefixes are declaration syntax only. For example, c.age refers to the age column; the data do not need a column named c.age. For factors, observed-level order follows levels(). Set factor levels before calling tab() or tabmulti() when exact ordering or reference categories are important.

vars() with no arguments remains an error by design. This avoids accidentally selecting every variable.

Value

A data frame of class r4vn_vars with columns variable, type, specification, and reference_index. Deferred selectors are expanded by .r4vn_resolve_vars() inside R4VN analysis functions.

See Also

tab and tabmulti.

Other R4VN tables: tab(), tabexport(), tabforest(), tablong(), tabmeta(), tabmulti(), tabscale(), tabscore(), tabsurvey()

Examples

# Existing declaration syntax.
specification <- vars(i.sex, b3.education, c.age, q.bmi, f.sbp)
specification
# i.sex is an explicit categorical declaration with the first level as reference.
vars(i.sex)

# Deferred selectors are captured by vars() and resolved by public
# R4VN analysis functions once a data frame is supplied.
vars(.)
vars(`kt*`)
vars(`*score`)
vars(`*kt*`)
vars(., -id)
vars(`c.lab*`, q.lab_crp)

dat <- data.frame(
  id = 1:5,
  age = c(31, 42, 38, 50, 46),
  sex = factor(c("F", "M", "F", "M", "F")),
  kt1 = 1:5,
  kt2 = 6:10,
  kt_total = 11:15,
  score_kt = 16:20
)

# Unprefixed variables are typed automatically from the actual data:
# age is numeric -> mean (SD); sex is a factor -> categorical.
t_auto <- tab(dat, vars = vars(age, sex), show = FALSE)

# Select all variables.
t_all <- tab(dat, vars = vars(.), show = FALSE)

# Prefix wildcard.
t_kt <- tab(dat, vars = vars(`kt*`), show = FALSE)

# Select all except id.
t_no_id <- tab(dat, vars = vars(., -id), show = FALSE)

# Typed wildcard with an exact override.
t_typed <- tab(
  dat,
  vars = vars(`c.kt*`, q.kt_total),
  show = FALSE
)

t_kt$data

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.