table_apa: Build APA-Style Cross-Tabulation Tables From Multiple Row...

In spicy: Descriptive Statistics and Data Management Tools

Build APA-Style Cross-Tabulation Tables From Multiple Row Variables

Description

table_apa() builds a publication-ready table by crossing one grouping variable (group_var) with one or many row variables (row_vars), using spicy::cross_tab() internally.

Usage

table_apa(
  data,
  row_vars,
  group_var,
  labels = NULL,
  levels_keep = NULL,
  include_total = TRUE,
  drop_na = TRUE,
  weights = NULL,
  rescale = FALSE,
  correct = FALSE,
  simulate_p = FALSE,
  simulate_B = 2000,
  percent_digits = 1,
  p_digits = 3,
  v_digits = 2,
  decimal_mark = ".",
  output = c("wide", "long", "tinytable", "flextable", "excel", "clipboard", "word"),
  style = c("auto", "raw", "report"),
  indent_text = "  ",
  indent_text_excel_clipboard = "      ",
  add_multilevel_header = TRUE,
  blank_na_wide = FALSE,
  excel_path = NULL,
  excel_sheet = "APA",
  clipboard_delim = "\t",
  word_path = NULL
)

Arguments

data	A data frame.
row_vars	Character vector of variable names to place in rows.
group_var	Single character variable name used for columns/groups.
labels	Optional character labels for row_vars (same length).
levels_keep	Optional character vector of levels to keep/order for row modalities. If NULL, all observed levels are kept.
include_total	Logical. If TRUE (the default), includes a Total group when available.
drop_na	Logical. If TRUE (the default), removes rows with NA in the row/group variable before each cross-tabulation. If FALSE, missing values are displayed as a dedicated "(Missing)" level.
weights	Optional weights. Either NULL (the default), a numeric vector of length nrow(data), or a single column name in data.
rescale	Logical. If FALSE (the default), weights are used as-is. If TRUE, rescales weights so total weighted N matches raw N. Passed to spicy::cross_tab().
correct	Logical. If FALSE (the default), no continuity correction is applied. If TRUE, applies Yates correction in 2x2 chi-squared contexts. Passed to spicy::cross_tab().
simulate_p	Logical. If FALSE (the default), uses asymptotic p-values. If TRUE, uses Monte Carlo simulation. Passed to spicy::cross_tab().
simulate_B	Integer. Number of Monte Carlo replicates when simulate_p = TRUE. Defaults to 2000.
percent_digits	Number of digits for percentages in report outputs. Defaults to 1.
p_digits	Number of digits for p-values (except ⁠< .001⁠). Defaults to 3.
v_digits	Number of digits for Cramer's V. Defaults to 2.
decimal_mark	Decimal separator ("." or ","). Defaults to ".".
output	Output format: "wide" (the default), "long", "tinytable", "flextable", "excel", "clipboard", "word".
style	"auto" (the default) to select by output type, "raw" for machine-friendly outputs, "report" for formatted outputs.
indent_text	Prefix used for modality labels in report table building. Defaults to " " (two spaces).
indent_text_excel_clipboard	Stronger indentation used in Excel and clipboard exports. Defaults to six non-breaking spaces.
add_multilevel_header	Logical. If TRUE (the default), merges top headers in Excel export.
blank_na_wide	Logical. If FALSE (the default), NA values are kept as-is in wide raw output. If TRUE, replaces them with empty strings.
excel_path	Path for output = "excel". Defaults to NULL.
excel_sheet	Sheet name for Excel export. Defaults to "APA".
clipboard_delim	Delimiter for clipboard text export. Defaults to "\t".
word_path	Path for output = "word" or optional save path when output = "flextable". Defaults to NULL.

Details

It supports raw data outputs (wide, long) and report-oriented outputs (tinytable, flextable, excel, clipboard, word) with multi-level headers, p-values, and Cramer's V.

Optional output engines require suggested packages:

• tinytable for output = "tinytable"

• flextable + officer for output = "flextable"/"word"

• openxlsx for output = "excel"

• clipr for output = "clipboard"

Value

Depends on output and style:

• "long" + "raw": long numeric data frame.

• "wide" + "raw": wide numeric data frame.

• "long" + "report": long formatted character data frame.

• "wide" + "report": wide formatted character data frame.

• "tinytable": a tinytable object.

• "flextable": a flextable object.

• "excel" / "clipboard" / "word": invisibly returns written object/path.

Examples

# Build a minimal reproducible dataset
d_ex <- transform(
  mtcars,
  hes = factor(gear, labels = c("BFH", "HEdS-Geneve", "HESAV")),
  emploi_sf = ifelse(vs == 1, "Oui", "Non"),
  role_prof_recherche = ifelse(am == 1, "Oui", "Non"),
  w = mpg
)

# Raw long output (machine-friendly)
table_apa(
  data = d_ex,
  row_vars = c("emploi_sf", "role_prof_recherche"),
  group_var = "hes",
  labels = c("Emploi SF", "Role recherche"),
  output = "long",
  style = "raw"
)

# Raw wide output
table_apa(
  data = d_ex,
  row_vars = c("emploi_sf", "role_prof_recherche"),
  group_var = "hes",
  labels = c("Emploi SF", "Role recherche"),
  output = "wide",
  style = "raw"
)

# Weighted example
table_apa(
  data = d_ex,
  row_vars = c("emploi_sf", "role_prof_recherche"),
  group_var = "hes",
  labels = c("Emploi SF", "Role recherche"),
  weights = "w",
  rescale = TRUE,
  simulate_p = FALSE,
  output = "long",
  style = "raw"
)


# Optional output: tinytable
if (requireNamespace("tinytable", quietly = TRUE)) {
  tt_ex <- table_apa(
    data = d_ex,
    row_vars = c("emploi_sf", "role_prof_recherche"),
    group_var = "hes",
    labels = c("Emploi SF", "Role recherche"),
    output = "tinytable"
  )
}

# Optional output: Excel
if (requireNamespace("openxlsx", quietly = TRUE)) {
  table_apa(
    data = d_ex,
    row_vars = c("emploi_sf", "role_prof_recherche"),
    group_var = "hes",
    labels = c("Emploi SF", "Role recherche"),
    output = "excel",
    excel_path = tempfile(fileext = ".xlsx")
  )
}

spicy documentation built on March 14, 2026, 5:06 p.m.