Skip to contents

Draw a table from a data.frame

Source: R/datasummary_df.R
datasummary_df.Rd

Draw a table from a data.frame

Usage

datasummary_df(
  data,
  output = getOption("modelsummary_output", default = "default"),
  fmt = 2,
  align = getOption("modelsummary_align", default = NULL),
  hrule = getOption("modelsummary_hrule", default = NULL),
  title = getOption("modelsummary_title", default = NULL),
  notes = getOption("modelsummary_notes", default = NULL),
  add_rows = getOption("modelsummary_add_rows", default = NULL),
  add_columns = getOption("modelsummary_add_columns", default = NULL),
  escape = getOption("modelsummary_escape", default = TRUE),
  ...
)

Arguments

data

A data.frame (or tibble)

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

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.

hrule

position of horizontal rules (integer vector)

title

string. Cross-reference labels should be added with Quarto or Rmarkdown chunk options when applicable. When saving standalone LaTeX files, users can add a label such as \\label{tab:mytable} directly to the title string, while also specifying escape=FALSE.

notes

list or vector of notes to append to the bottom of the 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. Positions can be defined using integers. In the modelsummary() function (only), you can also use string shortcuts: "coef_start", "coef_end", "gof_start", "gof_end"

  • attr(new_rows, 1:2)

  • attr(new_rows, "gof_start") See Examples section below.

add_columns

a data.frame (or tibble) with the same number of rows as your main table.

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.

Version 2.0.0, kableExtra, and tinytable

Since version 2.0.0, modelsummary uses tinytable as its default table-drawing backend. Learn more at: https://vincentarelbundock.github.io/tinytable/",

Revert to kableExtra for one session:

options(modelsummary_factory_default = 'kableExtra') options(modelsummary_factory_latex = 'kableExtra') options(modelsummary_factory_html = 'kableExtra')

References

Arel-Bundock V (2022). “modelsummary: Data and Model Summaries in R.” Journal of Statistical Software, 103(1), 1-23. doi:10.18637/jss.v103.i01 .'