table_apa: Build APA-Style Cross-Tabulation Tables

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,
  assoc_measure = "auto",
  assoc_ci = FALSE,
  decimal_mark = ".",
  output = c("wide", "long", "tinytable", "gt", "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
)

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.
"gt": a gt_tbl object.
"flextable": a flextable object.
"excel" / "clipboard" / "word": invisibly returns written object/path.

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 the association measure. Defaults to 2.
assoc_measure: Passed to cross_tab(). Which association measure to report ("auto", "cramer_v", "phi", "gamma", "tau_b", "tau_c", "somers_d", "lambda", "none"). Defaults to "auto".
assoc_ci: Passed to cross_tab(). If TRUE, includes the confidence interval. In data/export formats (wide, long, excel, clipboard), two extra columns CI lower and CI upper are added. In rendered formats (gt, tinytable, flextable, word), the CI is shown inline as .14 [.08, .19] in the association measure column. Defaults to FALSE.
decimal_mark: Decimal separator ("." or ","). Defaults to ".".
output: Output format: "wide" (the default), "long", "tinytable", "gt", "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 an association measure.

Optional output engines require suggested packages:

tinytable for output = "tinytable"
gt for output = "gt"
flextable + officer for output = "flextable"/"word"
openxlsx for output = "excel"
clipr for output = "clipboard"

Examples

Run this code

# Raw long output (machine-friendly)
table_apa(
  data = sochealth,
  row_vars = c("smoking", "physical_activity"),
  group_var = "education",
  labels = c("Current smoker", "Physical activity"),
  output = "long",
  style = "raw"
)

# Raw wide output
table_apa(
  data = sochealth,
  row_vars = c("smoking", "physical_activity"),
  group_var = "education",
  labels = c("Current smoker", "Physical activity"),
  output = "wide",
  style = "raw"
)

# Weighted example
table_apa(
  data = sochealth,
  row_vars = c("smoking", "physical_activity"),
  group_var = "education",
  labels = c("Current smoker", "Physical activity"),
  weights = "weight",
  rescale = TRUE,
  simulate_p = FALSE,
  output = "long",
  style = "raw"
)

# \donttest{
# Optional output: tinytable
if (requireNamespace("tinytable", quietly = TRUE)) {
  table_apa(
    data = sochealth,
    row_vars = c("smoking", "physical_activity"),
    group_var = "education",
    labels = c("Current smoker", "Physical activity"),
    output = "tinytable"
  )
}

# Optional output: Excel
if (requireNamespace("openxlsx", quietly = TRUE)) {
  table_apa(
    data = sochealth,
    row_vars = c("smoking", "physical_activity"),
    group_var = "education",
    labels = c("Current smoker", "Physical activity"),
    output = "excel",
    excel_path = tempfile(fileext = ".xlsx")
  )
}
# }

Run the code above in your browser using DataLab