Summary tables for APA-style reporting

Choose the right function

Use the function that matches the unit you want to report:

In practice, follow the APA sequence:

• start with table_categorical() for smoking, education, or activity — APA Table 1 categorical descriptors;
• use table_continuous() for BMI, well-being, or income — Table 1 continuous descriptors and Table 2 unadjusted group comparisons;
• switch to table_continuous_lm() when the same comparison must account for survey weights, robust SE, or covariate adjustment;
• finish with table_regression() once the substantive model is fitted — APA Table 3 with all predictors, factor groupings, reference rows, and (optionally) standardised coefficients, marginal effects, or nested model comparisons.

The first three functions live inside a select / by data-frame grammar; table_regression() is fit-first — you build the model the usual R way (lm() or glm()) and hand the object in. All four share the post-construction grammar (output, labels, digits, decimal_mark, align), so swapping functions never breaks your rendering pipeline.

A shared interface

The three descriptive functions share the same core arguments:

table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = education,
  labels = c("Smoking status", "Regular physical activity"),
  output = "tinytable"
)
#> Found litedown! Enabling r-universe template

table_continuous(
  sochealth,
  select = c(bmi, wellbeing_score, life_sat_health),
  by = education,
  labels = c(
    bmi = "Body mass index",
    wellbeing_score = "Well-being score",
    life_sat_health = "Satisfaction with health"
  ),
  output = "tinytable"
)

table_continuous_lm(
  sochealth,
  select = c(bmi, wellbeing_score, life_sat_health),
  by = education,
  weights = weight
)
#> Continuous outcomes by Highest education level
#> 
#>  Variable                       │ M (Lower secondary)  M (Upper secondary) 
#> ────────────────────────────────┼──────────────────────────────────────────
#>  Body mass index                │        25.96                23.39        
#>  WHO-5 wellbeing index (0-100)  │        67.55                80.88        
#>  Satisfaction with health (1-5) │         3.45                 4.39        
#> 
#>  Variable                       │ M (Tertiary)    p     R²    n   
#> ────────────────────────────────┼─────────────────────────────────
#>  Body mass index                │    26.16      <.001  0.13  1188 
#>  WHO-5 wellbeing index (0-100)  │    66.52      <.001  0.19  1200 
#>  Satisfaction with health (1-5) │     3.39      <.001  0.15  1192

The same argument pattern is used in all three cases:

• select chooses the reported variables;
• by defines the grouping structure;
• labels cleans up the row labels;
• output decides how the result is rendered or exported.

For model-based continuous tables, the same pattern applies, but by must be a single predictor because one linear model is fit per outcome.

table_regression() joins the same labels / output / decimal_mark / digits grammar but is fit-first: rather than expressing model structure inline through select and by, you pass one or several already-fitted lm() or glm() objects:

fit <- lm(
  wellbeing_score ~ age + sex + smoking + physical_activity,
  data = sochealth
)
table_regression(
  fit,
  labels = c(
    age               = "Age (years)",
    sex               = "Sex",
    smoking           = "Smoking status",
    physical_activity = "Regular physical activity"
  ),
  output = "tinytable"
)

This split is intentional. The descriptive trio (categorical, continuous, continuous_lm) reports the data — select and by describe what you want to see. table_regression() reports the model — the model formula has already declared which predictors, interactions, polynomials, transformations, splines, and contrasts to report, so passing those again through select / by would duplicate the model object’s information and risk diverging from it.

A practical reporting sequence

A common report contains both table types, often with the same grouping variable. For example, you might first summarize categorical health behaviors, then summarize continuous well-being indicators.

pkgdown_dark_gt(
  table_categorical(
    sochealth,
    select = c(smoking, physical_activity, dentist_12m),
    by = education,
    labels = c(
      "Smoking status",
      "Regular physical activity",
      "Visited a dentist in the last 12 months"
    ),
    output = "gt"
  )
)

pkgdown_dark_gt(
  table_continuous(
    sochealth,
    select = c(bmi, wellbeing_score, life_sat_health),
    by = education,
    labels = c(
      bmi = "Body mass index",
      wellbeing_score = "Well-being score",
      life_sat_health = "Satisfaction with health"
    ),
    p_value = TRUE,
    effect_size = TRUE,
    output = "gt"
  )
)

pkgdown_dark_gt(
  table_continuous_lm(
    sochealth,
    select = c(bmi, wellbeing_score, life_sat_health),
    by = sex,
    vcov = "HC3",
    statistic = TRUE,
    output = "gt"
  )
)

fit <- lm(
  wellbeing_score ~ age + sex + smoking + physical_activity,
  data = sochealth
)
pkgdown_dark_gt(
  table_regression(
    fit,
    standardized = "refit",
    show_columns = c("b", "beta", "ci", "p"),
    vcov = "HC3",
    output = "gt"
  )
)

fit_unadj <- lm(wellbeing_score ~ smoking, data = sochealth)
fit_adj   <- lm(
  wellbeing_score ~ smoking + age + sex + physical_activity,
  data = sochealth
)
pkgdown_dark_gt(
  table_regression(
    list("Unadjusted" = fit_unadj, "Adjusted" = fit_adj),
    show_columns = c("b", "ci", "p"),
    output = "gt"
  )
)

fit_glm <- glm(
  smoking ~ age + sex + physical_activity,
  data = sochealth,
  family = binomial()
)
pkgdown_dark_gt(
  table_regression(
    fit_glm,
    exponentiate = TRUE,
    show_columns = c("b", "ci", "p", "ame", "ame_ci"),
    output = "gt"
  )
)

Choose the output format

All four functions support the same reporting formats:

Pick the output based on where the table is going, not on the analysis itself. The underlying selection and grouping pattern stays the same.

If you want an object that fits naturally into Word and PowerPoint workflows but can also be rendered in HTML documents, flextable is a good choice:

if (requireNamespace("flextable", quietly = TRUE)) {
  table_continuous(
    sochealth,
    select = c(bmi, wellbeing_score, life_sat_health),
    by = education,
    output = "flextable"
  )
}

Post-process the returned table object

All four summary-table helpers return regular gt, tinytable, or flextable objects, so you can keep styling them with the native package API. This includes table_regression(): nothing about the fit-first interface changes what the rendering engine produces.

Use gt:: functions when you want to keep the gt workflow:

tab <- pkgdown_dark_gt(table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = education,
  labels = c("Smoking status", "Regular physical activity"),
  output = "gt"
))

tab |>
  gt::tab_header(
    title = "Health behaviors by education",
    subtitle = "Categorical summary table"
  ) |>
  gt::tab_source_note(
    gt::md("*Percentages are computed within each education group.*")
  )

Use tinytable:: functions when you want lightweight table-specific styling:

tab <- table_categorical(
  sochealth,
  select = c(smoking, physical_activity),
  by = education,
  labels = c("Smoking status", "Regular physical activity"),
  output = "tinytable"
)

tab |>
  tinytable::style_tt(
    i = 2:3,
    j = 2:5,
    background = "red",
    color = "white",
    bold = TRUE
  )

Use flextable:: functions when you want to keep working toward Office or HTML document output. The example is shown as code here because the dark pkgdown theme is not a reliable preview of the final flextable HTML rendering:

if (requireNamespace("flextable", quietly = TRUE)) {
  tab <- table_continuous(
    sochealth,
    select = c(bmi, wellbeing_score),
    by = education,
    output = "flextable"
  )

  tab |>
    flextable::theme_booktabs() |>
    flextable::autofit() |>
    flextable::fontsize(size = 10, part = "all")
}

Keep the detailed options in the function-specific articles

The dedicated articles go deeper into each function:

• table_categorical() covers missing values, level filtering, association measures, and one-way frequency-style tables.
• table_continuous() covers grouped descriptive statistics, parametric and nonparametric tests, and effect sizes.
• table_continuous_lm() covers estimated marginal means or slopes from linear models, robust / cluster-robust / bootstrap / jackknife variance, case weights, additive covariate adjustment (G-computation or equal-weight), and four effect-size families with noncentral CIs.
• table_regression() covers single- and multi-model coefficient tables for lm / glm, four standardisation methods, partial effect sizes with noncentral-F CIs, average marginal effects, hierarchical (nested = TRUE) comparisons, multiplicity correction, and response-scale reporting for GLMs.

Use this vignette as the final reporting overview, then consult the function-specific articles when you need the detailed controls.