knitr::opts_chunk$set(collapse = T, comment = "#>") library(pander)
Core functionality of pander
is centered around pandoc.table
which is aimed at rendering tables in markdown
. In case of 2D tables, pander
calls pandoc.table
internally, thus in such cases pander
and pandoc.table
support the same argument and in this vignette will be used iterchangingly. pandoc.table
has big variety of options (highlighting, styles, etc.) and this vignette aims to give a more details overview of most common options. pander
comes with a variety of globally adjustable options, which have an effect on the result of your reports. You can query and update these options with the panderOptions
function.
Since pander
aims at rendering R objects into Pandoc's markdown all four (multiline
, simple
, grid
, rmarkdown
) of Pandoc's formats are supported. General advices is to stick with default multiline
style, but if there is a need to change it either specify style
argument when calling pander/pandoc.table
or change default style
using panderOptions
.
multiline
tables allow headers and table rows to span multiple lines of text (but cells that span multiple columns or rows of the table are not supported). Also note, that, by default, line breaks are removed from cells for simplicity, so multiline cells are typically the result of splitting large cells or setting keep.line.breaks
to TRUE
:
m <- data.frame('Value\n1', 'Value\n2') colnames(m) <- c('Multiline\nCol1', 'Multiline\nCol2') pandoc.table(m, keep.line.breaks = TRUE) m <- mtcars[1:3, 1:4] pandoc.table(m)
simple
tables are have more compact syntax that all other styles, but don't they support multiline cells:
m <- mtcars[1:3, 1:4] pandoc.table(m, style = 'simple') m <- data.frame('Value\n1', 'Value\n2') colnames(m) <- c('Multiline\nCol1', 'Multiline\nCol2') pandoc.table(m, keep.line.breaks = TRUE, style='simple')
grid
format is really handy for emacs
users (Emacs table mod) and it does support block elements (multiple paragraphs, code blocks, lists, etc.) inside cells. Alignments are not supported for grid tables by most parsers, meaning that even though pander
will produce a table with alightnment, it will be lost during conversion from markdown
to HTML/PDF/DOCX
, and cells can't span multiple columns or rows.
m <- mtcars[1:3, 1:4] pandoc.table(m, style = 'grid') m <- data.frame('Value\n1', 'Value\n2') colnames(m) <- c('Multiline\nCol1', 'Multiline\nCol2') pandoc.table(m, keep.line.breaks = TRUE, style='grid')
rmarkdown
or pipe table format is often used directly with knitr
, since it was supportered by the first versions of the markdown
package. It is similar to simple
table, meaning that multiline cells are not supported. The beginning and ending pipe characters are optional, but pipes are required between all columns:
m <- mtcars[1:3, 1:4] pandoc.table(m, style = 'rmarkdown') m <- data.frame('Value\n1', 'Value\n2') colnames(m) <- c('Multiline\nCol1', 'Multiline\nCol2') pandoc.table(m, keep.line.breaks = TRUE, style='rmarkdown')
pander
allows users to control cell alignment (left
, right
or center/centre
) in a table directly by setting the justify
parameter when calling pander/pandoc.table
. Note that it is possible to specify alighnment for each column separately by supplying a vector to justify:
pandoc.table(head(iris[,1:3], 2), justify = 'right') pandoc.table(head(iris[,1:3], 2), justify = c('right', 'center', 'left'))
Another possible way to define alignment is by using a permanent option table.alignment.default/table.alignment.rownames
in panderOptions
(prefered way) or by using set.alignment
function (legacy way of setting alignment for next table or permanently) which support setting alignment separately for cells and rownames:
set.alignment('left', row.names = 'right') # set only for next table since permanent parameter is falce pandoc.table(mtcars[1:2, 1:5])
Interesting application for this functionality is specifying a function that takes the R object as its argument to compute some unique alignment for your table based on e.g. column values or variable types:
panderOptions('table.alignment.default', function(df) ifelse(sapply(df, mean) > 2, 'left', 'right')) pandoc.table(head(iris[,1:3], 2)) panderOptions('table.alignment.default', 'center')
One of the great features of pander
is the ease of highlighting rows, columns and cells in a table. This is a native markdown
feature without custom HTML
or LaTeX
-only tweaks, so all HTML/PDF/MS Word/OpenOffice
etc. formats are supported.
This can be achieved by specifying one of the arguments below when calling pander
/pandoc.table
or change default style using panderOptions
:
The emphasize.italics
helpers would turn the affected cells to italic, emphasize.strong
would apply a bold style to the cell and emphasize.verbatim
would apply a verbatim
style to the cell. A cell can be also italic, bold and verbatim
at the same time.
Those functions and arguments ending in rows or cols take a vector (like which columns or rows to emphasize in a table), while the cells argument take either a vector (for one dimensional "tables") or an array-like data structure with two columns holding row and column indexes of cells to be emphasized -- just like what which(..., arr.ind = TRUE)
returns:
t <- mtcars[1:3, 1:5] emphasize.italics.cols(1) emphasize.italics.rows(1) emphasize.strong.cells(which(t > 20, arr.ind = TRUE)) pandoc.table(t) pandoc.table(t, emphasize.verbatim.rows = 1, emphasize.strong.cells = which(t > 20, arr.ind = TRUE))
For more ellaborative examples, please see our blog post - Highlight cells in markdown tables.
pander/pandoc.table
is able to deal with the problem of wide tables. Ever had an issue in LaTeX
or MS Word
when tried to print a correlation matrix of 40 variables? This problem is carefully addressed with split.table
parameter:
pandoc.table(mtcars[1:2, ], style = "grid", caption = "Wide table to be split!")
split.table
defaults to 80 characters and to turn it off, set split.table
to Inf
:
pandoc.table(mtcars[1:2, ], style = "grid", caption = "Wide table to be split!", split.table = Inf)
Also, pander
tries to split too wide cells into multiline cells. The maximum number of characters in a cell is specified by split.cells
parameter (defaults to 30), which can be a single value, vector (values for each column separately) and relative vector (percentages of split.tables
parameter). Please not that this only works for multiline
and grid
tables:
df <- data.frame(a = 'Lorem ipsum', b = 'dolor sit', c = 'amet') pandoc.table(df, split.cells = 5) pandoc.table(df, split.cells = c(5, 20, 5)) pandoc.table(df, split.cells = c("80%", "10%", "10%")) pandoc.table(df, split.cells = 5, style = 'simple')
In some cases it is also useful to split too long words like with hyphens, and pander
uses koRpus
functionality for that. Just specify use.hyphening
argument and have koRpus
installed:
pandoc.table(data.frame(baz = 'foobar', foo='accoutrements'), use.hyphening = TRUE, split.cells = 3)
pander/pandoc.table
deals with formatting numbers by having 4 parameters:
round
to the number of decimal places. digits
to specify how many significant digits are to be used for numericdecimal.mark/big.mark
to specify character for decimal point/orders of magnitude round
and digits
param can be a vector specifying values for each column (has to be the same length as number of columns). Values for non-numeric columns will be disregarded.
Now let's get to some examples:
r <- matrix(c(283764.97430, 29.12345678901, -7.1234, -100.1), ncol = 2) pandoc.table(r, round = 2) pandoc.table(r, round = c(4,2)) # vector for each column pandoc.table(r, digits = 2) pandoc.table(r, digits = c(0, 5)) # vector for each column pandoc.table(r, big.mark = ',') pandoc.table(r, decimal.mark = ',')
Funtionality described in other sections is most notable, but pander/pandoc.table
also has smaller nifty features that are worth mentioning:
plain.ascii
- allows to have the output without markdown
markup:pandoc.table(mtcars[1:3, 1:4]) pandoc.table(mtcars[1:3, 1:4], plain.ascii = TRUE)
caption
- set caption (string) to be shown under the table:pandoc.table(mtcars[1:3, 1:5], style = "grid", caption = "My caption!")
missing
- set a string to replace missing values:m <- mtcars[1:3, 1:5] m$mpg <- NA pandoc.table(m, missing = '?')
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.