Exporting data frames into nice tables
The export_table()
functions creates nicely formatted
tables in text, markdown or HTML format. You can add (coloured) captions
or footer lines to the table as well, and you can even create multiple
tables from a list of data frames.
This vignette shows some examples how to do this (focusing on text
output). Note that export_table()
returns a formatted
string, which prints nicely (which essentially just uses
cat()
).
Note: The vignettes includes example with
coloured text output. The coloured text is not rendered in this
vignette. Rather, try out these examples and look at the results in your
console!
library(insight)
x <- iris[1:3, c(1, 2, 5)]
# the table as "readable" output
export_table(x)
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
# see the underlying string
unclass(export_table(x))
#> [1] "Sepal.Length | Sepal.Width | Species\n------------------------------------\n 5.10 | 3.50 | setosa\n 4.90 | 3.00 | setosa\n 4.70 | 3.20 | setosa\n"
Adding (coloured) titles
A title can be added by either using the caption
argument, or by adding a string as table_caption
attribute.
# a simple caption
export_table(x, caption = "Title")
#> Title
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
# we use a new object, so "x" has no attributes yet
out <- x
attr(out, "table_caption") <- "Another title"
export_table(out)
#> Another title
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
caption
can also be character vector of length 2, with
the first element being the caption, and the second being the name of a
colour (see ?print_colour
for available options). This is
helpful for printing coloured table captions.
# A red caption
export_table(x, caption = c("# Title", "red"))
#> # Title
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
# same for attribute
out <- x
attr(out, "table_caption") <- c("*A green title*", "green")
export_table(out)
#> *A green title*
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
Since the coloured text is not rendered, we provide a screenshot as
example here:
Adding subtitles
Subtitles can be added using the subtitle
argument, or
the table_subtitle
attribute. Note that you must take care
of adding new-line characters.
# colored caption, subtitle and footer
export_table(
x,
caption = c("# Title", "red"),
subtitle = c("\n A subtitle in yellow", "yellow"),
footer = c("Footer line in blue", "blue")
)
#> # Title
#> A subtitle in yellow
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#> Footer line in blue
# as attribute
out <- x
attr(out, "table_caption") <- c("*A green title*", "green")
attr(out, "table_subtitle") <- c("\nA yellow subtitle", "yellow")
attr(out, "table_footer") <- c("Footer line in blue", "blue")
export_table(out)
#> *A green title*
#> A yellow subtitle
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#> Footer line in blue
Exporting multiple data frames into multiple tables
Multiple data frames saved in a list()
can be used to
create multiple tables at once.
x <- list(
data.frame(iris[1:3, c(1, 2, 5)]),
data.frame(iris[51:53, c(1, 3, 5)]),
data.frame(iris[111:113, c(1, 4, 5)])
)
# three different tables
export_table(x)
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#>
#> Sepal.Length | Petal.Length | Species
#> ----------------------------------------
#> 7.00 | 4.70 | versicolor
#> 6.40 | 4.50 | versicolor
#> 6.90 | 4.90 | versicolor
#>
#> Sepal.Length | Petal.Width | Species
#> --------------------------------------
#> 6.50 | 2.00 | virginica
#> 6.40 | 1.90 | virginica
#> 6.80 | 2.10 | virginica
Adding table captions and footers
For multiple tables, it is also possible to add a caption for each
table. Simply use a list()
of strings for the
caption
argument, or add a table_caption
attribute. to each data frame in the list.
# one caption for each table
export_table(x, caption = list("Table 1", "Table 2", "Table 3"))
#> Table 1
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#>
#> Table 2
#>
#> Sepal.Length | Petal.Length | Species
#> ----------------------------------------
#> 7.00 | 4.70 | versicolor
#> 6.40 | 4.50 | versicolor
#> 6.90 | 4.90 | versicolor
#>
#> Table 3
#>
#> Sepal.Length | Petal.Width | Species
#> --------------------------------------
#> 6.50 | 2.00 | virginica
#> 6.40 | 1.90 | virginica
#> 6.80 | 2.10 | virginica
# add attribute to *each* data frame
out <- x
for (i in seq_along(out)) {
attr(out[[i]], "table_caption") <- paste("Table", i)
}
export_table(out)
#> Table 1
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#>
#> Table 2
#>
#> Sepal.Length | Petal.Length | Species
#> ----------------------------------------
#> 7.00 | 4.70 | versicolor
#> 6.40 | 4.50 | versicolor
#> 6.90 | 4.90 | versicolor
#>
#> Table 3
#>
#> Sepal.Length | Petal.Width | Species
#> --------------------------------------
#> 6.50 | 2.00 | virginica
#> 6.40 | 1.90 | virginica
#> 6.80 | 2.10 | virginica
In the same way you can add multiple footers. Note, however, that you
have to take care about adding new-line characters.
# add captions and footers for each table
export_table(
x,
caption = list("Table 1", "Table 2", "Table 3"),
footer = list("Footer 1\n\n", "Footer 2\n\n", "Footer 3\n\n")
)
#> Table 1
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#> Footer 1
#>
#>
#> Table 2
#>
#> Sepal.Length | Petal.Length | Species
#> ----------------------------------------
#> 7.00 | 4.70 | versicolor
#> 6.40 | 4.50 | versicolor
#> 6.90 | 4.90 | versicolor
#> Footer 2
#>
#>
#> Table 3
#>
#> Sepal.Length | Petal.Width | Species
#> --------------------------------------
#> 6.50 | 2.00 | virginica
#> 6.40 | 1.90 | virginica
#> 6.80 | 2.10 | virginica
#> Footer 3
out <- x
for (i in seq_along(out)) {
attr(out[[i]], "table_caption") <- paste("Table", i)
attr(out[[i]], "table_footer") <- paste("Footer", i, "\n\n")
}
export_table(out)
#> Table 1
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#> Footer 1
#>
#>
#> Table 2
#>
#> Sepal.Length | Petal.Length | Species
#> ----------------------------------------
#> 7.00 | 4.70 | versicolor
#> 6.40 | 4.50 | versicolor
#> 6.90 | 4.90 | versicolor
#> Footer 2
#>
#>
#> Table 3
#>
#> Sepal.Length | Petal.Width | Species
#> --------------------------------------
#> 6.50 | 2.00 | virginica
#> 6.40 | 1.90 | virginica
#> 6.80 | 2.10 | virginica
#> Footer 3
Finally, you can even add multiple footer lines to each table, giving
each a different color. In this case, each list element has to be a
character vector of length 2 (the first element being the caption, and
the second being the name of a colour).
# Colored table captions and multiple footers per table
export_table(
x,
caption = list(
c("Red Table 1", "red"),
c("Blue Table 2", "bue"),
c("Green Table 3", "green")
),
footer = list(
list(c("Footer line 1\n", "green"), c("Second line\n\n", "red")),
list(c("Footer line A\n", "blue"), c("Second line\n\n", "green")),
list(c("Footer line I\n", "yellow"), c("Second line\n\n", "blue"))
)
)
#> Red Table 1
#>
#> Sepal.Length | Sepal.Width | Species
#> ------------------------------------
#> 5.10 | 3.50 | setosa
#> 4.90 | 3.00 | setosa
#> 4.70 | 3.20 | setosa
#> Footer line 1
#> Second line
#>
#>
#> Blue Table 2
#>
#> Sepal.Length | Petal.Length | Species
#> ----------------------------------------
#> 7.00 | 4.70 | versicolor
#> 6.40 | 4.50 | versicolor
#> 6.90 | 4.90 | versicolor
#> Footer line A
#> Second line
#>
#>
#> Green Table 3
#>
#> Sepal.Length | Petal.Width | Species
#> --------------------------------------
#> 6.50 | 2.00 | virginica
#> 6.40 | 1.90 | virginica
#> 6.80 | 2.10 | virginica
#> Footer line I
#> Second line