Tables

Standard Pandoc tables

Simple tables are easy to create. Header and rows must be on two lines, and column alignment is determined according to the position of the header relative to the line under it. Tables must be surrounded by empty lines and an optional caption may be added above or below the table, starting with Table: or : (which is stripped off).

Demonstration of a simple table with caption.
Right	Left	Center	Default
12	12	12	12
123	123	123	123
1	1	1	1

The header may be omitted, but then, the ending line is mandatory.

A table without header.
12	12	12	12
123	123	123	123
1	1	1	1

Multiline tables start and end with a line of dashes. Cells are separated by spaces (in case of a single row table, add the empty line too, otherwise, the table is interpreted as a single-line table). In multiline tables, the writer tries to respect the relative size of the columns that appear in the markdown document.

A multiline table.
Centered Header	Default Aligned	Right Aligned	Left Aligned
First	row	12.0	* Example of a row that spans multiple lines.
Second	row	5.0	* Here’s another one. Note the blank line between rows.

Headers can be omitted too in multiline tables (note that this could be used as a simple formatting hack to place –short– material on several columns!):

Here’s a multiline table without headers.
First	row	12.0	Example of a row that spans multiple lines.
Second	row	5.0	Here’s another one. Note the blank line between rows.

Grid tables (rows with = separate headers and can be omitted for headerless tables). Apparently, more formatting is allowed in gridded tables, like list items:

Sample grid table.
Fruit	Price	Advantages
Bananas	$1.34	built-in wrapper bright color
Oranges	$2.10	cures scurvy tasty

Pipe tables look like this (beginning and end pipes are optional, and optional colon indicates alignment, header can be omitted but not the lines, and finally, although ugly, pipe do not need to align). Note that table characters like | cannot appear in the table and this form does not support multiline tables. The semicolumn : may be used to indicate alignment inside each column, but it is an optional feature.

A typical pipe table.
Right	Left	Default	Center
12	12	12	12
123	123	123	123
* 1	1	1	1

Tables using ‘knitr::kable()’

The {knitr} package provides the function kable() to format data frames as Markdown tables, and it is very easy to use:

knitr::kable(head(iris))

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

Tables using {xtable}

The {xtable} R package offers an alternative to output well-formatted tables in an R Markdown document (note that you must specify type = "html" or type = "latex" (default) and a way to automate it is provided here depending on the R Markdown output and indicate results='asis' in the chunk header):

library(xtable)
data(tli)
# Demonstrate data.frame... can also export many objects!
tli.table <- xtable(tli[1:10, ])
digits(tli.table)[c(2, 6)] <- 0
# Choose 'one of these!'html' or 'latex' automatically
options(xtable.type = if (knitr::is_html_output()) "html" else "latex")
print(tli.table, floating = FALSE) # or add type = "html"|"latex")

	grade	sex	disadvg	ethnicty	tlimth
1	6	M	YES	HISPANIC	43
2	7	M	NO	BLACK	88
3	5	F	YES	HISPANIC	34
4	3	M	YES	HISPANIC	65
5	8	M	YES	WHITE	75
6	5	M	NO	BLACK	74
7	8	F	YES	HISPANIC	72
8	4	M	YES	BLACK	79
9	6	M	NO	WHITE	88
10	7	M	YES	HISPANIC	87

Tables using {pander}

The {pander} R package can output various objects in Pandoc:

library(pander)
# You can change default pander options:
panderOptions('table.alignment.default', function(df)
  ifelse(sapply(df, is.numeric), 'right', 'left'))
panderOptions('table.split.table', Inf)
panderOptions('big.mark', ",")
panderOptions('keep.trailing.zeros', TRUE)
pander(head(iris))

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

Tables using {flextable}

The {flextable} R package allows for fine customization of the formatted table using a pipeline-compatible approach:

library(flextable)

## 
## Attaching package: 'flextable'

## The following object is masked from 'package:xtable':
## 
##     align

library(dplyr)

## 
## Attaching package: 'dplyr'

## The following objects are masked from 'package:stats':
## 
##     filter, lag

## The following objects are masked from 'package:base':
## 
##     intersect, setdiff, setequal, union

mtcars %>%
  group_by(., cyl, am) %>%
  summarise(., avg = mean(mpg)) %>%
  flextable(.) %>%
  bg(., bg = '#c7deff', part = 'header')

## `summarise()` has grouped output by 'cyl'. You can override using the `.groups`
## argument.

cyl	am	avg
4	0	22.90000
4	1	28.07500
6	0	19.12500
6	1	20.56667
8	0	15.05000
8	1	15.40000

There are many other packages to output well-formatted tables from R objects, like: {stargazer}, {table1}, {tables}, {formattable}, {htmlTable}, {huxtable}, {kableExtra}, {pixiedust}, {tangram}, {texreg}, {ztable}, etc.

Table numbers and references

Standard Pandoc does not allow to number tables and figures, nor to refer to them in text, like it is usual to do in the scientific litterature. If the Markdown document is converted into LaTeX (to produce a PDF, or Beamer presentation, for instance), one can add LaTeX tags to do so. However, these tags will not work obviously with HTML outputs. The {bookdown} format extends the Markdown syntax to allow numbered tables and cross-references with @ref(label) tags, see here. In {blogdown}, providing you generate your tables with knitr::kable(), and you indicate a caption = argument.

The first few lines of the `iris` data set.
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

Now, you can refer to this table in the text in {blogdown} using a link like this [this Table](#tab:table-iris), where table-iris is the name of the chunk that generated the table. In {blogdown}, it gives this (see this Table), but in {pkgdown}, it does not work. The {svSweave} R package can generate numbers for tables, figures and equations, and it allows for cross-referencing them in the text using pure R code. Thus, it works with all R Markdown documents, see the svSweave documentation.

Philippe Grosjean (phgrosjean@sciviews.org)

2020-04-16