Balance table: Summary statistics for different subsets of the data (e.g., control and treatment groups)

Description

Creates balance tables with summary statistics for different subsets of the data (e.g., control and treatment groups). It can also be used to create summary tables for full data sets. See the Details and Examples sections below, and the vignettes on the modelsummary website:

• https://modelsummary.com/

• https://modelsummary.com/articles/datasummary.html

Usage

datasummary_balance(
  formula,
  data,
  output = "default",
  fmt = fmt_decimal(digits = 1, pdigits = 3),
  title = NULL,
  notes = NULL,
  align = NULL,
  stars = FALSE,
  add_columns = NULL,
  add_rows = NULL,
  dinm = TRUE,
  dinm_statistic = "std.error",
  escape = TRUE,
  ...
)

Arguments

formula	~1: show summary statistics for the full dataset one-sided formula: with the "condition" or "column" variable on the right-hand side. two-side formula: with the subset of variables to summarize on the left-hand side and the condition variable on the right-hand side.
data	A data.frame (or tibble). If this data includes columns called "blocks", "clusters", and/or "weights", the "estimatr" package will consider them when calculating the difference in means. If there is a weights column, the reported mean and standard errors will also be weighted.
output	filename or object type (character string) Supported filename extensions: .docx, .html, .tex, .md, .txt, .csv, .xlsx, .png, .jpg Supported object types: "default", "html", "markdown", "latex", "latex_tabular", "typst", "data.frame", "tinytable", "gt", "kableExtra", "huxtable", "flextable", "DT", "jupyter". The "modelsummary_list" value produces a lightweight object which can be saved and fed back to the modelsummary function. The "default" output format can be set to "tinytable", "kableExtra", "gt", "flextable", "huxtable", "DT", or "markdown" If the user does not choose a default value, the packages listed above are tried in sequence. Session-specific configuration: options(“modelsummary_factory_default” = “gt”) Persistent configuration: config_modelsummary(output = “markdown”) Warning: Users should not supply a file name to the output argument if they intend to customize the table with external packages. See the ‘Details’ section. LaTeX compilation requires the booktabs and siunitx packages, but siunitx can be disabled or replaced with global options. See the ‘Details’ section.
fmt	how to format numeric values: integer, user-supplied function, or modelsummary function. Integer: Number of decimal digits User-supplied functions: Any function which accepts a numeric vector and returns a character vector of the same length. modelsummary functions: fmt = fmt_significant(2): Two significant digits (at the term-level) fmt = fmt_sprintf(“%.3f”): See ?sprintf fmt = fmt_identity(): unformatted raw values
title	string
notes	list or vector of notes to append to the bottom of the table.
align	A string with a number of characters equal to the number of columns in the table (e.g., align = “lcc”). Valid characters: l, c, r, d. "l": left-aligned column "c": centered column "r": right-aligned column "d": dot-aligned column. For LaTeX/PDF output, this option requires at least version 3.0.25 of the siunitx LaTeX package. See the LaTeX preamble help section below for commands to insert in your LaTeX preamble.
stars	to indicate statistical significance FALSE (default): no significance stars. TRUE: +=.1, =.05, =.01, =0.001 Named numeric vector for custom stars such as c(’*’ = .1, ‘+’ = .05) Note: a legend will not be inserted at the bottom of the table when the estimate or statistic arguments use "glue strings" with stars.
add_columns	a data.frame (or tibble) with the same number of rows as your main table.
add_rows	a data.frame (or tibble) with the same number of columns as your main table. By default, rows are appended to the bottom of the table. You can define a "position" attribute of integers to set the row positions. See Examples section below.
dinm	TRUE calculates a difference in means with uncertainty estimates. This option is only available if the estimatr package is installed. If data includes columns named "blocks", "clusters", or "weights", this information will be taken into account automatically by estimatr::difference_in_means.
dinm_statistic	string: "std.error" or "p.value"
escape	boolean TRUE escapes or substitutes LaTeX/HTML characters which could prevent the file from compiling/displaying. TRUE escapes all cells, captions, and notes. Users can have more fine-grained control by setting escape=FALSE and using an external command such as: modelsummary(model, “latex”) |> tinytable::format_tt(tab, j=1:5, escape=TRUE)
…	all other arguments are passed through to the table-making functions tinytable::tt, kableExtra::kbl, gt::gt, DT::datatable, etc. depending on the output argument. This allows users to pass arguments directly to datasummary in order to affect the behavior of other functions behind the scenes.

Global Options

The behavior of modelsummary can be modified by setting global options. For example:

• options(modelsummary_model_labels = “roman”)

The rest of this section describes each of the options above.

Model labels: default column names

These global option changes the style of the default column headers:

• options(modelsummary_model_labels = “roman”)

• options(modelsummary_panel_labels = “roman”)

The supported styles are: "model", "panel", "arabic", "letters", "roman", "(arabic)", "(letters)", "(roman)"

The panel-specific option is only used when shape=“rbind”

Table-making packages

modelsummary supports 6 table-making packages: tinytable, kableExtra, gt, flextable, huxtable, and DT. Some of these packages have overlapping functionalities. To change the default backend used for a specific file format, you can use ’ the options function:

options(modelsummary_factory_html = ‘kableExtra’) options(modelsummary_factory_latex = ‘gt’) options(modelsummary_factory_word = ‘huxtable’) options(modelsummary_factory_png = ‘gt’)

Table themes

Change the look of tables in an automated and replicable way, using the modelsummary theming functionality. See the vignette: https://modelsummary.com/articles/appearance.html

• modelsummary_theme_gt

• modelsummary_theme_kableExtra

• modelsummary_theme_huxtable

• modelsummary_theme_flextable

• modelsummary_theme_dataframe

Model extraction functions

modelsummary can use two sets of packages to extract information from statistical models: the easystats family (performance and parameters) and broom. By default, it uses easystats first and then falls back on broom in case of failure. You can change the order of priorities or include goodness-of-fit extracted by both packages by setting:

options(modelsummary_get = “easystats”)

options(modelsummary_get = “broom”)

options(modelsummary_get = “all”)

Formatting numeric entries

By default, LaTeX tables enclose all numeric entries in the command from the siunitx package. To prevent this behavior, or to enclose numbers in dollar signs (for LaTeX math mode), users can call:

options(modelsummary_format_numeric_latex = “plain”)

options(modelsummary_format_numeric_latex = “mathmode”)

A similar option can be used to display numerical entries using MathJax in HTML tables:

options(modelsummary_format_numeric_html = “mathjax”)

LaTeX preamble

When creating LaTeX via the tinytable backend (default in version 2.0.0 and later), it is useful to include the following commands in the LaTeX preamble of your documents. Note that they are added automatically when compiling Rmarkdown or Quarto documents.

[3]{}

Examples

library(modelsummary)

library(modelsummary)
datasummary_balance(~am, mtcars)

	0		1
	Mean	Std. Dev.	Mean	Std. Dev.	Diff. in Means	Std. Error
mpg	17.1	3.8	24.4	6.2	7.2	1.9
cyl	6.9	1.5	5.1	1.6	-1.9	0.6
disp	290.4	110.2	143.5	87.2	-146.8	35.0
hp	160.3	53.9	126.8	84.1	-33.4	26.4
drat	3.3	0.4	4.0	0.4	0.8	0.1
wt	3.8	0.8	2.4	0.6	-1.4	0.2
qsec	18.2	1.8	17.4	1.8	-0.8	0.6
vs	0.4	0.5	0.5	0.5	0.2	0.2
gear	3.2	0.4	4.4	0.5	1.2	0.2
carb	2.7	1.1	2.9	2.2	0.2	0.7