The content of the tables can be altered with the function's arguments, or by calling options, as described in the Details section below. The look of the tables can be customized by specifying the output argument, and by using functions from one of the supported table customization packages: kableExtra, gt, flextable, huxtable.

The modelsummary_list output type is a lightweight representation of the model results. The modelsummary function can export to this format by setting the output argument, and it can accept objects of this format as input models to create a table. This can be useful to save raw results, in order to print a table later, without having to save and extract from the entire model object. Note that the confidence intervals are only stored in a modelsummary_list if explicitly requested:

msummary(
  models,
  output = "default",
  fmt = 3,
  estimate = "estimate",
  statistic = "std.error",
  vcov = NULL,
  conf_level = 0.95,
  stars = FALSE,
  coef_map = NULL,
  coef_omit = NULL,
  coef_rename = NULL,
  gof_map = NULL,
  gof_omit = NULL,
  group = term ~ model,
  group_map = NULL,
  add_rows = NULL,
  align = NULL,
  notes = NULL,
  title = NULL,
  escape = TRUE,
  ...
)

Arguments

models

a model or (optionally named) list of models

output

filename or object type (character string)

  • Supported filename extensions: .html, .tex, .md, .txt, .png, .jpg.

  • Supported object types: "default", "html", "markdown", "latex", "latex_tabular", "data.frame", "modelsummary_list", "gt", "kableExtra", "huxtable", "flextable", "jupyter".

  • 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.

  • The default output formats and table-making packages can be modified with global options. See the 'Details' section.

fmt

determines how to format numeric values

  • integer: the number of digits to keep after the period format(round(x, fmt), nsmall=fmt)

  • character: passed to the sprintf function (e.g., '%.3f' keeps 3 digits with trailing zero). See ?sprintf

  • function: returns a formatted character string.

  • Note on LaTeX formatting: To ensure proper typography, all numeric entries are enclosed in the \num{} command from the siunitx LaTeX package by default. This behavior can be altered with global options. See the 'Details' section.

estimate

string or glue string of the estimate to display (or a vector with one string per model). Valid entries include any column name of the data.frame produced by get_estimates(model). Examples:

  • "estimate"

  • "{estimate} ({std.error}){stars}"

  • "{estimate} [{conf.low}, {conf.high}]"

statistic

vector of strings or glue strings which select uncertainty statistics to report vertically below the estimate. NULL omits all uncertainty statistics.

  • "conf.int", "std.error", "statistic", "p.value", "conf.low", "conf.high", or any column name produced by: get_estimates(model)

  • glue package strings with braces, such as:

    • "{p.value} [{conf.low}, {conf.high}]"

    • "Std.Error: {std.error}"

  • Note: Parentheses are added automatically unless the string includes glue curly braces {}.

  • Note: To report uncertainty statistics next to coefficients, you can #' supply a glue string to the estimate argument.

vcov

robust standard errors and other manual statistics. The vcov argument accepts six types of input (see the 'Details' and 'Examples' sections below):

  • NULL returns the default uncertainty estimates of the model object

  • string, vector, or (named) list of strings. Omitting or specifying vcov = NULL will return the model's default uncertainty estimates, e.g. IID errors for standard models. Alternatively, use the string "iid" (aliases: "classical" or "constant") to present IID errors explicitly. The strings "HC", "HC0", "HC1" (alias: "stata"), "HC2", "HC3" (alias: "robust"), "HC4", "HC4m", "HC5", "HAC", "NeweyWest", "Andrews", "panel-corrected", "outer-product", and "weave" use variance-covariance matrices computed using functions from the sandwich package, or equivalent method. The behavior of those functions can (and sometimes must) be altered by passing arguments to sandwich directly from modelsummary through the ellipsis (...), but it is safer to define your own custom functions as described in the next bullet.

  • function or (named) list of functions which return variance-covariance matrices with row and column names equal to the names of your coefficient estimates (e.g., stats::vcov, sandwich::vcovHC, function(x) vcovPC(x, cluster="country")).

  • formula or (named) list of formulas with the cluster variable(s) on the right-hand side (e.g., ~clusterid).

  • (named) list of length(models) variance-covariance matrices with row and column names equal to the names of your coefficient estimates.

  • a (named) list of length(models) vectors with names equal to the names of your coefficient estimates. See 'Examples' section below. Warning: since this list of vectors can include arbitrary strings or numbers, modelsummary cannot automatically calculate p values. The stars argument may thus use incorrect significance thresholds when vcov is a list of vectors.

conf_level

confidence level to use for confidence intervals

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}.

coef_map

character vector. Subset, rename, and reorder coefficients. Coefficients omitted from this vector are omitted from the table. The order of the vector determines the order of the table. coef_map can be a named or an unnamed character vector (see the Examples section below). If coef_map is a named vector, its values define the labels that must appear in the table, and its names identify the original term names stored in the model object: c("hp:mpg"="HPxM/G").

coef_omit

string regular expression. Omits all matching coefficients from the table using grepl(perl=TRUE). This argument uses perl-compatible regular expressions, which allows expressions such as "Int|ABC" which omits coefficients matching either "Int" or "ABC", and "^(?!.*Intercept)"` which omits every term except the intercept.

coef_rename

named character vector or function which returns a named vector. Values of the vector refer to the variable names that will appear in the table. Names refer to the original term names stored in the model object, e.g. c("hp:mpg"="hp X mpg") for an interaction term.

gof_map

rename, reorder, and omit goodness-of-fit statistics and other model information. This argument accepts 3 types of values:

  • NULL (default): the modelsummary::gof_map dictionary is used for formatting, and all unknown statistic are included.

  • data.frame with 3 columns named "raw", "clean", "fmt". Unknown statistics are omitted. See the 'Examples' section below.

  • list of lists, each of which includes 3 elements named "raw", "clean", "fmt". Unknown statistics are omitted. See the 'Examples section below'.

gof_omit

string regular expression. Omits all matching gof statistics from the table. This argument uses perl-compatible regular expressions (grepl(perl=TRUE)), which allows expressions such as ".*" which omits everything, and "^(?!R2|Num)" which omits every term except those that start with "R2" or "Num".

group

a two-sided formula with two or three components which describes how groups of parameters should be displayed. The formula must include both a "term" and a "model" component. In addition, a component can be used to identify groups of parameters (e.g., outcome levels of a multinomial logit model). This group identifier must be the name of a column in the data.frame produced by get_estimates(model).

  • term ~ model displays coefficients as rows and models as columns

  • model ~ term displays models as rows and coefficients as columns

  • response + term ~ model displays response levels and coefficients as rows and models as columns.

group_map

named or unnamed character vector. Subset, rename, and reorder coefficient groups specified in the group argument. See coef_map.

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.

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, S.

  • "l": left-aligned column

  • "c": centered column

  • "r": right-aligned column

  • "d": dot-aligned column. Only supported for LaTeX/PDF tables produced by kableExtra. These commands must appear in the LaTeX preamble (they are added automatically when compiling Rmarkdown documents to PDF):

    • \usepackage{booktabs}

    • \usepackage{siunitx}

    • \newcolumntype{d}{S[input-symbols = ()]}

notes

list or vector of notes to append to the bottom of the table.

title

string

escape

boolean TRUE escapes or substitutes LaTeX/HTML characters which could prevent the file from compiling/displaying. This setting does not affect captions or notes.

...

all other arguments are passed through to the extractor and table-making functions. This allows users to pass arguments directly to modelsummary in order to affect the behavior of other functions behind the scenes. Examples include:

Value

a regression table in a format determined by the output argument.

Details

backup <- modelsummary(models, output = "modelsummary_list" statistic = "conf.int") modelsummary(backup)

When a file name with a valid extension is supplied to the output argument, the table is written immediately to file. If you want to customize your table by post-processing it with an external package, you need to choose a different output format and saving mechanism. Unfortunately, the approach differs from package to package:

  • gt: set output="gt", post-process your table, and use the gt::gtsave function.

  • kableExtra: set output to your destination format (e.g., "latex", "html", "markdown"), post-process your table, and use kableExtra::save_kable function.

vcov

To use a string such as "robust" or "HC0", your model must be supported by the sandwich package. This includes objects such as: lm, glm, survreg, coxph, mlogit, polr, hurdle, zeroinfl, and more.

NULL, "classical", "iid", and "constant" are aliases which do not modify uncertainty estimates and simply report the default standard errors stored in the model object.

One-sided formulas such as ~clusterid are passed to the sandwich::vcovCL function.

Matrices and functions producing variance-covariance matrices are first passed to lmtest. If this does not work, modelsummary attempts to take the square root of the diagonal to adjust "std.error", but the other uncertainty estimates are not be adjusted.

Numeric vectors are formatted according to fmt and placed in brackets. Character vectors printed as given, without parentheses.

If your model type is supported by the lmtest package, the vcov argument will try to use that package to adjust all the uncertainty estimates, including "std.error", "statistic", "p.value", and "conf.int". If your model is not supported by lmtest, only the "std.error" will be adjusted by, for example, taking the square root of the matrix's diagonal.

Global Options

The behavior of modelsummary can be affected by setting global options:

  • modelsummary_factory_default

  • modelsummary_factory_latex

  • modelsummary_factory_html

  • modelsummary_factory_png

  • modelsummary_get

  • modelsummary_format_numeric_latex

  • modelsummary_format_numeric_html

Table-making packages

modelsummary supports 4 table-making packages: kableExtra, gt, flextable, and huxtable. Some of these packages have overlapping functionalities. For example, 3 of those packages can export to LaTeX. 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')

Model extraction functions

modelsummary can use two sets of packages to extract information from statistical models: broom and the easystats family (performance and parameters). By default, it uses broom first and easystats as a fallback if broom fails. You can change the order of priorities or include goodness-of-fit extracted by both packages by setting:

options(modelsummary_get = "broom") options(modelsummary_get = "easystats") options(modelsummary_get = "all")

Formatting numeric entries

By default, LaTeX tables enclose all numeric entries in the \num{} 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")

Examples

if (FALSE) { # The `modelsummary` website includes \emph{many} examples and tutorials: # https://vincentarelbundock.github.io/modelsummary library(modelsummary) # load data and estimate models data(trees) models <- list() models[['Bivariate']] <- lm(Girth ~ Height, data = trees) models[['Multivariate']] <- lm(Girth ~ Height + Volume, data = trees) # simple table modelsummary(models) # statistic modelsummary(models, statistic = NULL) modelsummary(models, statistic = 'p.value') modelsummary(models, statistic = 'statistic') modelsummary(models, statistic = 'conf.int', conf_level = 0.99) modelsummary(models, statistic = c("t = {statistic}", "se = {std.error}", "conf.int")) # estimate modelsummary(models, statistic = NULL, estimate = "{estimate} [{conf.low}, {conf.high}]") modelsummary(models, estimate = c("{estimate}{stars}", "{estimate} ({std.error})")) # vcov modelsummary(models, vcov = "robust") modelsummary(models, vcov = list("classical", "stata")) modelsummary(models, vcov = sandwich::vcovHC) modelsummary(models, vcov = list(stats::vcov, sandwich::vcovHC)) modelsummary(models, vcov = list(c("(Intercept)"="", "Height"="!"), c("(Intercept)"="", "Height"="!", "Volume"="!!"))) # vcov with custom names modelsummary( models, vcov = list("Stata Corp" = "stata", "Newey Lewis & the News" = "NeweyWest")) # coef_rename modelsummary(models, coef_map = c('Volume' = 'Large', 'Height' = 'Tall')) # coef_map modelsummary(models, coef_map = c('Volume' = 'Large', 'Height' = 'Tall')) modelsummary(models, coef_map = c('Volume', 'Height')) # title modelsummary(models, title = 'This is the title') # title with LaTeX label (for numbering and referencing) modelsummary(models, title = 'This is the title \\label{tab:description}') # add_rows rows <- tibble::tribble(~term, ~Bivariate, ~Multivariate, 'Empty row', '-', '-', 'Another empty row', '?', '?') attr(rows, 'position') <- c(1, 3) modelsummary(models, add_rows = rows) # notes modelsummary(models, notes = list('A first note', 'A second note')) # gof_map: data.frame gm <- modelsummary::gof_map gof_custom$omit[gof_custom$raw == 'deviance'] <- FALSE gof_custom$fmt[gof_custom$raw == 'r.squared'] <- "%.5f" modelsummary(models, gof_map = gof_custom) # gof_map: list of lists f1 <- function(x) format(round(x, 3), big.mark=",") f2 <- function(x) format(round(x, 0), big.mark=",") gm <- list( list("raw" = "nobs", "clean" = "N", "fmt" = f2), list("raw" = "AIC", "clean" = "aic", "fmt" = f1)) modelsummary(models, fmt = f1, gof_map = gm) }