Data frame and Tables Pretty Formatting
Usage
export_table(
x,
sep = " | ",
header = "-",
cross = NULL,
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,
table_width = NULL,
verbose = TRUE,
...
)
Arguments
- x
A data frame. May also be a list of data frames, to export multiple data frames into multiple tables.
- sep
Column separator.
- header
Header separator. Can be
NULL
.- cross
Character that is used where separator and header lines cross.
- 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, ordigits = "signif5"
for 5 significant figures (see alsosignif()
).- 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 forNA
.- width
Refers to the width of columns (with numeric values). Can be either
NULL
, a number or a named numeric vector. IfNULL
, the width for each column is adjusted to the minimum required width. If a number, columns with numeric values will have the minimum width specified inwidth
. If a named numeric vector, value names are matched against column names, and for each match, the specified width is used (see 'Examples'). Only applies to text-format (seeformat
).- format
Name of output-format, as string. If
NULL
(or"text"
), returned output is used for basic printing. Can be one ofNULL
(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 aliastable_caption
, andtable_subtitle
). Ifx
is a list of data frames,caption
may be a list of table captions, one for each table.- 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. If
x
is a list of data frames,footer
may be a list of table captions, one for each 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. Ifformat = "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 whenformat = "html"
.group_by
is passed down togt::gt(groupname_col = group_by)
.- zap_small
Logical, if
TRUE
, small values are rounded afterdigits
decimal places. IfFALSE
, values with more decimal places thandigits
are printed in scientific notation.- table_width
Numeric, or
"auto"
, indicating the width of the complete table. Iftable_width = "auto"
and the table is wider than the current width (i.e. line length) of the console (or any other source for textual output, like markdown files), the table is split into two parts. Else, iftable_width
is numeric and table rows are larger thantable_width
, the table is split into two parts.- verbose
Toggle messages and warnings.
- ...
Currently not used.
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
.
Examples
export_table(head(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
export_table(head(iris), cross = "+")
#> 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
export_table(head(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
# split longer tables
export_table(head(iris), table_width = 30)
#> Sepal.Length | Sepal.Width
#> --------------------------
#> 5.10 | 3.50
#> 4.90 | 3.00
#> 4.70 | 3.20
#> 4.60 | 3.10
#> 5.00 | 3.60
#> 5.40 | 3.90
#>
#> Sepal.Length | Petal.Length
#> ---------------------------
#> 5.10 | 1.40
#> 4.90 | 1.40
#> 4.70 | 1.30
#> 4.60 | 1.50
#> 5.00 | 1.40
#> 5.40 | 1.70
#>
#> Sepal.Length | Petal.Width | Species
#> ------------------------------------
#> 5.10 | 0.20 | setosa
#> 4.90 | 0.20 | setosa
#> 4.70 | 0.20 | setosa
#> 4.60 | 0.20 | setosa
#> 5.00 | 0.20 | setosa
#> 5.40 | 0.40 | setosa
# \donttest{
# colored footers
data(iris)
x <- as.data.frame(iris[1:5, ])
attr(x, "table_footer") <- c("This is a yellow footer line.", "yellow")
export_table(x)
#> 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
#> This is a yellow footer line.
attr(x, "table_footer") <- list(
c("\nA yellow line", "yellow"),
c("\nAnd a red line", "red"),
c("\nAnd a blue line", "blue")
)
export_table(x)
#> 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
#>
#> A yellow line
#> And a red line
#> And a blue line
attr(x, "table_footer") <- list(
c("Without the ", "yellow"),
c("new-line character ", "red"),
c("we can have multiple colors per line.", "blue")
)
export_table(x)
#> 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
#> Without the new-line character we can have multiple colors per line.
# }
# column-width
d <- data.frame(
x = c(1, 2, 3),
y = c(100, 200, 300),
z = c(10000, 20000, 30000)
)
export_table(d)
#> x | y | z
#> ---------------
#> 1 | 100 | 10000
#> 2 | 200 | 20000
#> 3 | 300 | 30000
export_table(d, width = 8)
#> x | y | z
#> ------------------------------
#> 1 | 100 | 10000
#> 2 | 200 | 20000
#> 3 | 300 | 30000
export_table(d, width = c(x = 5, z = 10))
#> x | y | z
#> ------------------------
#> 1 | 100 | 10000
#> 2 | 200 | 20000
#> 3 | 300 | 30000
export_table(d, width = c(x = 5, y = 5, z = 10), align = "lcr")
#> x | y | z
#> --------------------------
#> 1 | 100 | 10000
#> 2 | 200 | 20000
#> 3 | 300 | 30000