tab1: Quick one-way frequency tables

In R4VN: Health Data Analysis and Publication-Ready Reporting

Quick one-way frequency tables

Description

Displays formatted frequency tables for one or more categorical variables in the Viewer, with optional Console output. Data may be supplied explicitly, but when data = NULL the active data set selected by usedf() is used.

Usage

tab1(
  ...,
  by = NULL,
  data = NULL,
  missing = c("ifany", "no", "always"),
  percent = "column",
  digits = 1,
  overall = TRUE,
  drop = TRUE,
  show = TRUE,
  console = FALSE
)

Arguments

...	One or more variables. An explicit data frame may be supplied as the first unnamed argument for backward-compatible R4VN syntax.
by	Optional grouping variables supplied as one bare name, c(sex, agegroup), or vars(sex, agegroup).
data	Optional data frame. When omitted, active data is used.
missing	Missing-value display: "no", "ifany", or "always". For grouping variables, "ifany" and "always" retain observed missing strata.
percent	Percentage denominator: "column" or "within" for the terminal stratum, "row" for each response level across strata, "cell" or "overall" for all eligible observations, or "none".
digits	Decimal places for percentages.
overall	Logical; display the unstratified overall distribution.
drop	Logical; omit unused factor levels.
show	Logical; open the formatted result in the Viewer. Default TRUE.
console	Logical; also print the traditional result in the Console. Default FALSE.

Details

by accepts one or more nested stratification variables. For example, by = c(sex, agegroup) first separates results by sex and then displays age-group-specific results inside each sex group. Three or more nested stratification variables are also supported.

Value

Invisibly returns an object of class r4vn_quick.

Examples

d <- data.frame(
  sex = factor(c("Female", "Male", "Female", "Male", "Female", "Male")),
  agegroup = factor(c("<40", "<40", "40+", "40+", "<40", "40+")),
  smoking = factor(c("No", "Yes", "No", "Yes", NA, "No")),
  vaccinated = factor(c("Yes", "No", "Yes", "Yes", "No", "No"))
)
usedf(d, quiet = TRUE)

tab1(smoking)
tab1(smoking, vaccinated)
tab1(smoking, by = sex)
tab1(smoking, vaccinated, by = c(sex, agegroup))
tab1(smoking, by = c(sex, agegroup), missing = "always")

usedf(clear = TRUE, quiet = TRUE)

# Extended usage examples

d <- data.frame(
  sex = factor(c("Female", "Male", "Female", "Male", "Female", "Male")),
  agegroup = factor(c("<40", "<40", "40+", "40+", "<40", "40+")),
  province = factor(c("HCMC", "HCMC", "HCMC", "Other", "Other", "Other")),
  smoking = factor(c("No", "Yes", "No", "Yes", NA, "No")),
  vaccinated = factor(c("Yes", "No", "Yes", "Yes", "No", "No"))
)
usedf(d)

# One or several categorical variables
tab1(smoking)
tab1(smoking, vaccinated)

# One level of stratification
tab1(smoking, by = sex)

# Nested stratification: age groups are shown within each sex
tab1(smoking, by = c(sex, agegroup))

# Three nested levels, evaluated in the supplied order
tab1(smoking, vaccinated, by = c(province, sex, agegroup))

# Percentage denominators
tab1(smoking, by = c(sex, agegroup), percent = "column")
tab1(smoking, by = c(sex, agegroup), percent = "row")
tab1(smoking, by = c(sex, agegroup), percent = "cell")
tab1(smoking, by = c(sex, agegroup), percent = "none")

# Missing values and unused factor levels
tab1(smoking, missing = "no")
tab1(smoking, missing = "ifany")
tab1(smoking, missing = "always", drop = FALSE)

# Hide the overall section or retain the result without printing
tab1(smoking, by = sex, overall = FALSE)
result <- tab1(smoking, by = sex, show = FALSE)
result$variables[[1]]$strata

# Explicit data remains supported
tab1(d, smoking, vaccinated, by = c(sex, agegroup))
tab1(smoking, data = d)

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