Data frame and Tables Pretty Formatting

export_table(
  x,
  sep = " | ",
  header = "-",
  empty_line = NULL,
  digits = 2,
  protect_integers = TRUE,
  missing = "",
  width = NULL,
  format = NULL,
  title = NULL,
  caption = title,
  subtitle = NULL,
  footer = NULL,
  align = NULL,
  group_by = NULL,
  zap_small = FALSE,
  verbose = TRUE
)

Arguments

x

A data frame.

sep

Column separator.

header

Header separator. Can be NULL.

empty_line

Separator used for empty lines. If NULL, line remains empty (i.e. filled with whitespaces).

digits

Number of digits for rounding or significant figures. May also be "signif" to return significant figures or "scientific" to return scientific notation. Control the number of digits by adding the value as suffix, e.g. digits = "scientific4" to have scientific notation with 4 decimal places, or digits = "signif5" for 5 significant figures (see also signif()).

protect_integers

Should integers be kept as integers (i.e., without decimals)?

missing

Value by which NA values are replaced. By default, an empty string (i.e. "") is returned for NA.

width

Minimum width of the returned string. If not NULL and width is larger than the string's length, leading whitespaces are added to the string.

format

Name of output-format, as string. If NULL (or "text"), returned output is used for basic printing. Can be one of NULL (the default) resp. "text" for plain text, "markdown" (or "md") for markdown and "html" for HTML output.

title, caption, subtitle

Table title (same as caption) and subtitle, as strings. If NULL, no title or subtitle is printed, unless it is stored as attributes (table_title, or its alias table_caption, and table_subtitle).

footer

Table footer, as string. For markdown-formatted tables, table footers, due to the limitation in markdown rendering, are actually just a new text line under the table.

align

Column alignment. For markdown-formatted tables, the default align = NULL will right-align numeric columns, while all other columns will be left-aligned. If format = "html", the default is left-align first column and center all remaining. May be a string to indicate alignment rules for the complete table, like "left", "right", "center" or "firstleft" (to left-align first column, center remaining); or maybe a string with abbreviated alignment characters, where the length of the string must equal the number of columns, for instance, align = "lccrl" would left-align the first column, center the second and third, right-align column four and left-align the fifth column. For HTML-tables, may be one of "center", "left" or "right".

group_by

Name of column in x that indicates grouping for tables. Only applies when format = "html". group_by is passed down to gt::gt(groupname_col = group_by).

zap_small

Logical, if TRUE, small values are rounded after digits decimal places. If FALSE, values with more decimal places than digits are printed in scientific notation.

verbose

Toggle messages and warnings.

Value

A data frame in character format.

Note

The values for caption, subtitle and footer can also be provided as attributes of x, e.g. if caption = NULL and x has attribute table_caption, the value for this attribute will be used as table caption. table_subtitle is the attribute for subtitle, and table_footer for footer.

See also

Examples

cat(export_table(iris))
#> Sepal.Length | Sepal.Width | Petal.Length | Petal.Width |    Species
#> --------------------------------------------------------------------
#>         5.10 |        3.50 |         1.40 |        0.20 |     setosa
#>         4.90 |        3.00 |         1.40 |        0.20 |     setosa
#>         4.70 |        3.20 |         1.30 |        0.20 |     setosa
#>         4.60 |        3.10 |         1.50 |        0.20 |     setosa
#>         5.00 |        3.60 |         1.40 |        0.20 |     setosa
#>         5.40 |        3.90 |         1.70 |        0.40 |     setosa
#>         4.60 |        3.40 |         1.40 |        0.30 |     setosa
#>         5.00 |        3.40 |         1.50 |        0.20 |     setosa
#>         4.40 |        2.90 |         1.40 |        0.20 |     setosa
#>         4.90 |        3.10 |         1.50 |        0.10 |     setosa
#>         5.40 |        3.70 |         1.50 |        0.20 |     setosa
#>         4.80 |        3.40 |         1.60 |        0.20 |     setosa
#>         4.80 |        3.00 |         1.40 |        0.10 |     setosa
#>         4.30 |        3.00 |         1.10 |        0.10 |     setosa
#>         5.80 |        4.00 |         1.20 |        0.20 |     setosa
#>         5.70 |        4.40 |         1.50 |        0.40 |     setosa
#>         5.40 |        3.90 |         1.30 |        0.40 |     setosa
#>         5.10 |        3.50 |         1.40 |        0.30 |     setosa
#>         5.70 |        3.80 |         1.70 |        0.30 |     setosa
#>         5.10 |        3.80 |         1.50 |        0.30 |     setosa
#>         5.40 |        3.40 |         1.70 |        0.20 |     setosa
#>         5.10 |        3.70 |         1.50 |        0.40 |     setosa
#>         4.60 |        3.60 |         1.00 |        0.20 |     setosa
#>         5.10 |        3.30 |         1.70 |        0.50 |     setosa
#>         4.80 |        3.40 |         1.90 |        0.20 |     setosa
#>         5.00 |        3.00 |         1.60 |        0.20 |     setosa
#>         5.00 |        3.40 |         1.60 |        0.40 |     setosa
#>         5.20 |        3.50 |         1.50 |        0.20 |     setosa
#>         5.20 |        3.40 |         1.40 |        0.20 |     setosa
#>         4.70 |        3.20 |         1.60 |        0.20 |     setosa
#>         4.80 |        3.10 |         1.60 |        0.20 |     setosa
#>         5.40 |        3.40 |         1.50 |        0.40 |     setosa
#>         5.20 |        4.10 |         1.50 |        0.10 |     setosa
#>         5.50 |        4.20 |         1.40 |        0.20 |     setosa
#>         4.90 |        3.10 |         1.50 |        0.20 |     setosa
#>         5.00 |        3.20 |         1.20 |        0.20 |     setosa
#>         5.50 |        3.50 |         1.30 |        0.20 |     setosa
#>         4.90 |        3.60 |         1.40 |        0.10 |     setosa
#>         4.40 |        3.00 |         1.30 |        0.20 |     setosa
#>         5.10 |        3.40 |         1.50 |        0.20 |     setosa
#>         5.00 |        3.50 |         1.30 |        0.30 |     setosa
#>         4.50 |        2.30 |         1.30 |        0.30 |     setosa
#>         4.40 |        3.20 |         1.30 |        0.20 |     setosa
#>         5.00 |        3.50 |         1.60 |        0.60 |     setosa
#>         5.10 |        3.80 |         1.90 |        0.40 |     setosa
#>         4.80 |        3.00 |         1.40 |        0.30 |     setosa
#>         5.10 |        3.80 |         1.60 |        0.20 |     setosa
#>         4.60 |        3.20 |         1.40 |        0.20 |     setosa
#>         5.30 |        3.70 |         1.50 |        0.20 |     setosa
#>         5.00 |        3.30 |         1.40 |        0.20 |     setosa
#>         7.00 |        3.20 |         4.70 |        1.40 | versicolor
#>         6.40 |        3.20 |         4.50 |        1.50 | versicolor
#>         6.90 |        3.10 |         4.90 |        1.50 | versicolor
#>         5.50 |        2.30 |         4.00 |        1.30 | versicolor
#>         6.50 |        2.80 |         4.60 |        1.50 | versicolor
#>         5.70 |        2.80 |         4.50 |        1.30 | versicolor
#>         6.30 |        3.30 |         4.70 |        1.60 | versicolor
#>         4.90 |        2.40 |         3.30 |        1.00 | versicolor
#>         6.60 |        2.90 |         4.60 |        1.30 | versicolor
#>         5.20 |        2.70 |         3.90 |        1.40 | versicolor
#>         5.00 |        2.00 |         3.50 |        1.00 | versicolor
#>         5.90 |        3.00 |         4.20 |        1.50 | versicolor
#>         6.00 |        2.20 |         4.00 |        1.00 | versicolor
#>         6.10 |        2.90 |         4.70 |        1.40 | versicolor
#>         5.60 |        2.90 |         3.60 |        1.30 | versicolor
#>         6.70 |        3.10 |         4.40 |        1.40 | versicolor
#>         5.60 |        3.00 |         4.50 |        1.50 | versicolor
#>         5.80 |        2.70 |         4.10 |        1.00 | versicolor
#>         6.20 |        2.20 |         4.50 |        1.50 | versicolor
#>         5.60 |        2.50 |         3.90 |        1.10 | versicolor
#>         5.90 |        3.20 |         4.80 |        1.80 | versicolor
#>         6.10 |        2.80 |         4.00 |        1.30 | versicolor
#>         6.30 |        2.50 |         4.90 |        1.50 | versicolor
#>         6.10 |        2.80 |         4.70 |        1.20 | versicolor
#>         6.40 |        2.90 |         4.30 |        1.30 | versicolor
#>         6.60 |        3.00 |         4.40 |        1.40 | versicolor
#>         6.80 |        2.80 |         4.80 |        1.40 | versicolor
#>         6.70 |        3.00 |         5.00 |        1.70 | versicolor
#>         6.00 |        2.90 |         4.50 |        1.50 | versicolor
#>         5.70 |        2.60 |         3.50 |        1.00 | versicolor
#>         5.50 |        2.40 |         3.80 |        1.10 | versicolor
#>         5.50 |        2.40 |         3.70 |        1.00 | versicolor
#>         5.80 |        2.70 |         3.90 |        1.20 | versicolor
#>         6.00 |        2.70 |         5.10 |        1.60 | versicolor
#>         5.40 |        3.00 |         4.50 |        1.50 | versicolor
#>         6.00 |        3.40 |         4.50 |        1.60 | versicolor
#>         6.70 |        3.10 |         4.70 |        1.50 | versicolor
#>         6.30 |        2.30 |         4.40 |        1.30 | versicolor
#>         5.60 |        3.00 |         4.10 |        1.30 | versicolor
#>         5.50 |        2.50 |         4.00 |        1.30 | versicolor
#>         5.50 |        2.60 |         4.40 |        1.20 | versicolor
#>         6.10 |        3.00 |         4.60 |        1.40 | versicolor
#>         5.80 |        2.60 |         4.00 |        1.20 | versicolor
#>         5.00 |        2.30 |         3.30 |        1.00 | versicolor
#>         5.60 |        2.70 |         4.20 |        1.30 | versicolor
#>         5.70 |        3.00 |         4.20 |        1.20 | versicolor
#>         5.70 |        2.90 |         4.20 |        1.30 | versicolor
#>         6.20 |        2.90 |         4.30 |        1.30 | versicolor
#>         5.10 |        2.50 |         3.00 |        1.10 | versicolor
#>         5.70 |        2.80 |         4.10 |        1.30 | versicolor
#>         6.30 |        3.30 |         6.00 |        2.50 |  virginica
#>         5.80 |        2.70 |         5.10 |        1.90 |  virginica
#>         7.10 |        3.00 |         5.90 |        2.10 |  virginica
#>         6.30 |        2.90 |         5.60 |        1.80 |  virginica
#>         6.50 |        3.00 |         5.80 |        2.20 |  virginica
#>         7.60 |        3.00 |         6.60 |        2.10 |  virginica
#>         4.90 |        2.50 |         4.50 |        1.70 |  virginica
#>         7.30 |        2.90 |         6.30 |        1.80 |  virginica
#>         6.70 |        2.50 |         5.80 |        1.80 |  virginica
#>         7.20 |        3.60 |         6.10 |        2.50 |  virginica
#>         6.50 |        3.20 |         5.10 |        2.00 |  virginica
#>         6.40 |        2.70 |         5.30 |        1.90 |  virginica
#>         6.80 |        3.00 |         5.50 |        2.10 |  virginica
#>         5.70 |        2.50 |         5.00 |        2.00 |  virginica
#>         5.80 |        2.80 |         5.10 |        2.40 |  virginica
#>         6.40 |        3.20 |         5.30 |        2.30 |  virginica
#>         6.50 |        3.00 |         5.50 |        1.80 |  virginica
#>         7.70 |        3.80 |         6.70 |        2.20 |  virginica
#>         7.70 |        2.60 |         6.90 |        2.30 |  virginica
#>         6.00 |        2.20 |         5.00 |        1.50 |  virginica
#>         6.90 |        3.20 |         5.70 |        2.30 |  virginica
#>         5.60 |        2.80 |         4.90 |        2.00 |  virginica
#>         7.70 |        2.80 |         6.70 |        2.00 |  virginica
#>         6.30 |        2.70 |         4.90 |        1.80 |  virginica
#>         6.70 |        3.30 |         5.70 |        2.10 |  virginica
#>         7.20 |        3.20 |         6.00 |        1.80 |  virginica
#>         6.20 |        2.80 |         4.80 |        1.80 |  virginica
#>         6.10 |        3.00 |         4.90 |        1.80 |  virginica
#>         6.40 |        2.80 |         5.60 |        2.10 |  virginica
#>         7.20 |        3.00 |         5.80 |        1.60 |  virginica
#>         7.40 |        2.80 |         6.10 |        1.90 |  virginica
#>         7.90 |        3.80 |         6.40 |        2.00 |  virginica
#>         6.40 |        2.80 |         5.60 |        2.20 |  virginica
#>         6.30 |        2.80 |         5.10 |        1.50 |  virginica
#>         6.10 |        2.60 |         5.60 |        1.40 |  virginica
#>         7.70 |        3.00 |         6.10 |        2.30 |  virginica
#>         6.30 |        3.40 |         5.60 |        2.40 |  virginica
#>         6.40 |        3.10 |         5.50 |        1.80 |  virginica
#>         6.00 |        3.00 |         4.80 |        1.80 |  virginica
#>         6.90 |        3.10 |         5.40 |        2.10 |  virginica
#>         6.70 |        3.10 |         5.60 |        2.40 |  virginica
#>         6.90 |        3.10 |         5.10 |        2.30 |  virginica
#>         5.80 |        2.70 |         5.10 |        1.90 |  virginica
#>         6.80 |        3.20 |         5.90 |        2.30 |  virginica
#>         6.70 |        3.30 |         5.70 |        2.50 |  virginica
#>         6.70 |        3.00 |         5.20 |        2.30 |  virginica
#>         6.30 |        2.50 |         5.00 |        1.90 |  virginica
#>         6.50 |        3.00 |         5.20 |        2.00 |  virginica
#>         6.20 |        3.40 |         5.40 |        2.30 |  virginica
#>         5.90 |        3.00 |         5.10 |        1.80 |  virginica
cat(export_table(iris, sep = " ", header = "*", digits = 1))
#> Sepal.Length Sepal.Width Petal.Length Petal.Width    Species
#> ************************************************************
#>          5.1         3.5          1.4         0.2     setosa
#>          4.9         3.0          1.4         0.2     setosa
#>          4.7         3.2          1.3         0.2     setosa
#>          4.6         3.1          1.5         0.2     setosa
#>          5.0         3.6          1.4         0.2     setosa
#>          5.4         3.9          1.7         0.4     setosa
#>          4.6         3.4          1.4         0.3     setosa
#>          5.0         3.4          1.5         0.2     setosa
#>          4.4         2.9          1.4         0.2     setosa
#>          4.9         3.1          1.5         0.1     setosa
#>          5.4         3.7          1.5         0.2     setosa
#>          4.8         3.4          1.6         0.2     setosa
#>          4.8         3.0          1.4         0.1     setosa
#>          4.3         3.0          1.1         0.1     setosa
#>          5.8         4.0          1.2         0.2     setosa
#>          5.7         4.4          1.5         0.4     setosa
#>          5.4         3.9          1.3         0.4     setosa
#>          5.1         3.5          1.4         0.3     setosa
#>          5.7         3.8          1.7         0.3     setosa
#>          5.1         3.8          1.5         0.3     setosa
#>          5.4         3.4          1.7         0.2     setosa
#>          5.1         3.7          1.5         0.4     setosa
#>          4.6         3.6          1.0         0.2     setosa
#>          5.1         3.3          1.7         0.5     setosa
#>          4.8         3.4          1.9         0.2     setosa
#>          5.0         3.0          1.6         0.2     setosa
#>          5.0         3.4          1.6         0.4     setosa
#>          5.2         3.5          1.5         0.2     setosa
#>          5.2         3.4          1.4         0.2     setosa
#>          4.7         3.2          1.6         0.2     setosa
#>          4.8         3.1          1.6         0.2     setosa
#>          5.4         3.4          1.5         0.4     setosa
#>          5.2         4.1          1.5         0.1     setosa
#>          5.5         4.2          1.4         0.2     setosa
#>          4.9         3.1          1.5         0.2     setosa
#>          5.0         3.2          1.2         0.2     setosa
#>          5.5         3.5          1.3         0.2     setosa
#>          4.9         3.6          1.4         0.1     setosa
#>          4.4         3.0          1.3         0.2     setosa
#>          5.1         3.4          1.5         0.2     setosa
#>          5.0         3.5          1.3         0.3     setosa
#>          4.5         2.3          1.3         0.3     setosa
#>          4.4         3.2          1.3         0.2     setosa
#>          5.0         3.5          1.6         0.6     setosa
#>          5.1         3.8          1.9         0.4     setosa
#>          4.8         3.0          1.4         0.3     setosa
#>          5.1         3.8          1.6         0.2     setosa
#>          4.6         3.2          1.4         0.2     setosa
#>          5.3         3.7          1.5         0.2     setosa
#>          5.0         3.3          1.4         0.2     setosa
#>          7.0         3.2          4.7         1.4 versicolor
#>          6.4         3.2          4.5         1.5 versicolor
#>          6.9         3.1          4.9         1.5 versicolor
#>          5.5         2.3          4.0         1.3 versicolor
#>          6.5         2.8          4.6         1.5 versicolor
#>          5.7         2.8          4.5         1.3 versicolor
#>          6.3         3.3          4.7         1.6 versicolor
#>          4.9         2.4          3.3         1.0 versicolor
#>          6.6         2.9          4.6         1.3 versicolor
#>          5.2         2.7          3.9         1.4 versicolor
#>          5.0         2.0          3.5         1.0 versicolor
#>          5.9         3.0          4.2         1.5 versicolor
#>          6.0         2.2          4.0         1.0 versicolor
#>          6.1         2.9          4.7         1.4 versicolor
#>          5.6         2.9          3.6         1.3 versicolor
#>          6.7         3.1          4.4         1.4 versicolor
#>          5.6         3.0          4.5         1.5 versicolor
#>          5.8         2.7          4.1         1.0 versicolor
#>          6.2         2.2          4.5         1.5 versicolor
#>          5.6         2.5          3.9         1.1 versicolor
#>          5.9         3.2          4.8         1.8 versicolor
#>          6.1         2.8          4.0         1.3 versicolor
#>          6.3         2.5          4.9         1.5 versicolor
#>          6.1         2.8          4.7         1.2 versicolor
#>          6.4         2.9          4.3         1.3 versicolor
#>          6.6         3.0          4.4         1.4 versicolor
#>          6.8         2.8          4.8         1.4 versicolor
#>          6.7         3.0          5.0         1.7 versicolor
#>          6.0         2.9          4.5         1.5 versicolor
#>          5.7         2.6          3.5         1.0 versicolor
#>          5.5         2.4          3.8         1.1 versicolor
#>          5.5         2.4          3.7         1.0 versicolor
#>          5.8         2.7          3.9         1.2 versicolor
#>          6.0         2.7          5.1         1.6 versicolor
#>          5.4         3.0          4.5         1.5 versicolor
#>          6.0         3.4          4.5         1.6 versicolor
#>          6.7         3.1          4.7         1.5 versicolor
#>          6.3         2.3          4.4         1.3 versicolor
#>          5.6         3.0          4.1         1.3 versicolor
#>          5.5         2.5          4.0         1.3 versicolor
#>          5.5         2.6          4.4         1.2 versicolor
#>          6.1         3.0          4.6         1.4 versicolor
#>          5.8         2.6          4.0         1.2 versicolor
#>          5.0         2.3          3.3         1.0 versicolor
#>          5.6         2.7          4.2         1.3 versicolor
#>          5.7         3.0          4.2         1.2 versicolor
#>          5.7         2.9          4.2         1.3 versicolor
#>          6.2         2.9          4.3         1.3 versicolor
#>          5.1         2.5          3.0         1.1 versicolor
#>          5.7         2.8          4.1         1.3 versicolor
#>          6.3         3.3          6.0         2.5  virginica
#>          5.8         2.7          5.1         1.9  virginica
#>          7.1         3.0          5.9         2.1  virginica
#>          6.3         2.9          5.6         1.8  virginica
#>          6.5         3.0          5.8         2.2  virginica
#>          7.6         3.0          6.6         2.1  virginica
#>          4.9         2.5          4.5         1.7  virginica
#>          7.3         2.9          6.3         1.8  virginica
#>          6.7         2.5          5.8         1.8  virginica
#>          7.2         3.6          6.1         2.5  virginica
#>          6.5         3.2          5.1         2.0  virginica
#>          6.4         2.7          5.3         1.9  virginica
#>          6.8         3.0          5.5         2.1  virginica
#>          5.7         2.5          5.0         2.0  virginica
#>          5.8         2.8          5.1         2.4  virginica
#>          6.4         3.2          5.3         2.3  virginica
#>          6.5         3.0          5.5         1.8  virginica
#>          7.7         3.8          6.7         2.2  virginica
#>          7.7         2.6          6.9         2.3  virginica
#>          6.0         2.2          5.0         1.5  virginica
#>          6.9         3.2          5.7         2.3  virginica
#>          5.6         2.8          4.9         2.0  virginica
#>          7.7         2.8          6.7         2.0  virginica
#>          6.3         2.7          4.9         1.8  virginica
#>          6.7         3.3          5.7         2.1  virginica
#>          7.2         3.2          6.0         1.8  virginica
#>          6.2         2.8          4.8         1.8  virginica
#>          6.1         3.0          4.9         1.8  virginica
#>          6.4         2.8          5.6         2.1  virginica
#>          7.2         3.0          5.8         1.6  virginica
#>          7.4         2.8          6.1         1.9  virginica
#>          7.9         3.8          6.4         2.0  virginica
#>          6.4         2.8          5.6         2.2  virginica
#>          6.3         2.8          5.1         1.5  virginica
#>          6.1         2.6          5.6         1.4  virginica
#>          7.7         3.0          6.1         2.3  virginica
#>          6.3         3.4          5.6         2.4  virginica
#>          6.4         3.1          5.5         1.8  virginica
#>          6.0         3.0          4.8         1.8  virginica
#>          6.9         3.1          5.4         2.1  virginica
#>          6.7         3.1          5.6         2.4  virginica
#>          6.9         3.1          5.1         2.3  virginica
#>          5.8         2.7          5.1         1.9  virginica
#>          6.8         3.2          5.9         2.3  virginica
#>          6.7         3.3          5.7         2.5  virginica
#>          6.7         3.0          5.2         2.3  virginica
#>          6.3         2.5          5.0         1.9  virginica
#>          6.5         3.0          5.2         2.0  virginica
#>          6.2         3.4          5.4         2.3  virginica
#>          5.9         3.0          5.1         1.8  virginica
if (FALSE) {
# colored footers
data(iris)
x <- as.data.frame(iris[1:5, ])
attr(x, "table_footer") <- c("This is a yellow footer line.", "yellow")
cat(export_table(x))

attr(x, "table_footer") <- list(
  c("\nA yellow line", "yellow"),
  c("\nAnd a red line", "red"),
  c("\nAnd a blue line", "blue")
)
cat(export_table(x))

attr(x, "table_footer") <- list(
  c("Without the ", "yellow"),
  c("new-line character ", "red"),
  c("we can have multiple colors per line.", "blue")
)
cat(export_table(x))
}