pander: pandoc.table.return – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

pander

pandoc.table.return

Create a table

Description

Creates a Pandoc's markdown style table with optional caption and some other tweaks. See 'Details' below.

Usage

pandoc.table.return(t, caption, digits = panderOptions("digits"),
  decimal.mark = panderOptions("decimal.mark"),
  big.mark = panderOptions("big.mark"), round = panderOptions("round"),
  missing = panderOptions("missing"), justify, style = c("multiline",
  "grid", "simple", "rmarkdown", "jira"),
  split.tables = panderOptions("table.split.table"),
  split.cells = panderOptions("table.split.cells"),
  keep.trailing.zeros = panderOptions("keep.trailing.zeros"),
  keep.line.breaks = panderOptions("keep.line.breaks"),
  plain.ascii = panderOptions("plain.ascii"),
  use.hyphening = panderOptions("use.hyphening"), row.names, col.names,
  emphasize.rownames = panderOptions("table.emphasize.rownames"),
  emphasize.rows, emphasize.cols, emphasize.cells, emphasize.strong.rows,
  emphasize.strong.cols, emphasize.strong.cells, emphasize.italics.rows,
  emphasize.italics.cols, emphasize.italics.cells, emphasize.verbatim.rows,
  emphasize.verbatim.cols, emphasize.verbatim.cells, ...)

Arguments

`t`	data frame, matrix or table
`caption`	caption (string) to be shown under the table
`digits`	passed to `format`. Can be a vector specifying values for each column (has to be the same length as number of columns).
`decimal.mark`	passed to `format`
`big.mark`	passed to `format`
`round`	passed to `round`. 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.
`missing`	string to replace missing values
`justify`	defines alignment in cells passed to `format`. Can be `left`, `right` or `centre`, which latter can be also spelled as `center`. Defaults to `centre`. Can be abbreviated to a string consisting of the letters `l`, `c` and `r` (e.g. 'lcr' instead of c('left', 'centre', 'right').
`style`	which Pandoc style to use: `simple`, `multiline`, `grid` or `rmarkdown`
`split.tables`	where to split wide tables to separate tables. The default value (`80`) suggests the conventional number of characters used in a line, feel free to change (e.g. to `Inf` to disable this feature) if you are not using a VT100 terminal any more :)
`split.cells`	where to split cells' text with line breaks. Default to `30`, to disable set to `Inf`. Can be also supplied as a vector, for each cell separately (if length(split.cells) == number of columns + 1, then first value in split.cells if for row names, and others are for columns). Supports relative (percentage) parameters in combination with split.tables.
`keep.trailing.zeros`	to show or remove trailing zeros in numbers on a column basis width
`keep.line.breaks`	(default: `FALSE`) if to keep or remove line breaks from cells in a table
`plain.ascii`	(default: `FALSE`) if output should be in plain ascii (without markdown markup) or not
`use.hyphening`	boolean (default: `FALSE`) if try to use hyphening when splitting large cells according to table.split.cells. Requires sylly.
`row.names`	if `FALSE`, row names are suppressed. A character vector of row names can also be specified here. By default, row names are included if `rownames(t)` is neither `NULL` nor identical to `1:nrow(x)`
`col.names`	a character vector of column names to be used in the table
`emphasize.rownames`	boolean (default: `TRUE`) if row names should be highlighted
`emphasize.rows`	deprecated for `emphasize.italics.rows` argument
`emphasize.cols`	deprecated for `emphasize.italics.cols` argument
`emphasize.cells`	deprecated for `emphasize.italics.cells` argument
`emphasize.strong.rows`	see `emphasize.italics.rows` but in bold
`emphasize.strong.cols`	see `emphasize.italics.cols` but in bold
`emphasize.strong.cells`	see `emphasize.italics.cells` but in bold
`emphasize.italics.rows`	a vector for a two dimensional table specifying which rows to emphasize
`emphasize.italics.cols`	a vector for a two dimensional table specifying which cols to emphasize
`emphasize.italics.cells`	a vector for one-dimensional tables or a matrix like structure with two columns for row and column indexes to be emphasized in two dimensional tables. See e.g. `which(..., arr.ind = TRUE)`
`emphasize.verbatim.rows`	see `emphasize.italics.rows` but in verbatim
`emphasize.verbatim.cols`	see `emphasize.italics.cols` but in verbatim
`emphasize.verbatim.cells`	see `emphasize.italics.cells` but in verbatim
`...`	unsupported extra arguments directly placed into `/dev/null`

Details

This function takes any tabular data as its first argument and will try to make it pretty like: rounding and applying digits and custom decimal.mark to numbers, auto-recognizing if row names should be included, setting alignment of cells and dropping trailing zeros by default.

pandoc.table also tries to split large cells with line breaks or even the whole table to separate parts on demand. Other arguments lets the use to highlight some rows/cells/cells in the table with italic or bold text style.

For more details please see the parameters above and passed arguments of panderOptions.

Value

By default this function outputs (see: cat) the result. If you would want to catch the result instead, then call pandoc.table.return instead.

Note

If caption is missing, then the value is first checked in t object's caption attribute and if not found in an internal buffer set by link{set.caption}. justify parameter works similarly, see set.alignment for details.

References

John MacFarlane (2012): _Pandoc User's Guide_. http://johnmacfarlane.net/pandoc/README.html

Examples

pandoc.table(mtcars)

# caption
pandoc.table(mtcars, 'Motor Trend Car Road Tests')

# other input/output formats
pandoc.table(mtcars[, 1:3], decimal.mark = ',')
pandoc.table(mtcars[, 1:3], decimal.mark = ',', justify = 'right')
pandoc.table(matrix(sample(1:1000, 25), 5, 5))
pandoc.table(matrix(runif(25), 5, 5))
pandoc.table(matrix(runif(25), 5, 5), digits = 5)
pandoc.table(matrix(runif(25),5,5), round = 1)
pandoc.table(table(mtcars$am))
pandoc.table(table(mtcars$am, mtcars$gear))
pandoc.table(table(state.division, state.region))
pandoc.table(table(state.division, state.region), justify = 'centre')

m <- data.frame(a = c(1, -500, 10320, 23, 77),
  b = runif(5),
  c = c('a', 'bb', 'ccc', 'dddd', 'eeeee'))
pandoc.table(m)
pandoc.table(m, justify = c('right', 'left', 'centre'))
pandoc.table(m, justify = 'rlc') # Same as upper statement

## splitting up too wide tables
pandoc.table(mtcars)
pandoc.table(mtcars, caption = 'Only once after the first part!')

## tables with line breaks in cells
## NOTE: line breaks are removed from table content in case keep.line.breaks is set to FALSE
## and added automatically based on "split.cells" parameter!
t <- data.frame(a = c('hundreds\nof\nmouses', '3 cats'), b=c('FOO is nice', 'BAR\nBAR2'))
pandoc.table(t)
pandoc.table(t, split.cells = 5)

## exporting tables in other Pandoc styles
pandoc.table(m)
pandoc.table(m, style = "grid")
pandoc.table(m, style = "simple")
pandoc.table(t, style = "grid")
pandoc.table(t, style = "grid", split.cells = 5)
tryCatch(pandoc.table(t, style = "simple", split.cells = 5),
  error = function(e) 'Yeah, no newline support in simple tables')

## highlight cells
t <- mtcars[1:3, 1:5]
pandoc.table(t$mpg, emphasize.italics.cells = 1)
pandoc.table(t$mpg, emphasize.strong.cells = 1)
pandoc.table(t$mpg, emphasize.italics.cells = 1, emphasize.strong.cells = 1)
pandoc.table(t$mpg, emphasize.italics.cells = 1:2)
pandoc.table(t$mpg, emphasize.strong.cells = 1:2)
pandoc.table(t, emphasize.italics.cells = which(t > 20, arr.ind = TRUE))
pandoc.table(t, emphasize.italics.cells = which(t == 6, arr.ind = TRUE))
pandoc.table(t, emphasize.verbatim.cells = which(t == 6, arr.ind = TRUE))
pandoc.table(t, emphasize.verbatim.cells = which(t == 6, arr.ind = TRUE),
 emphasize.italics.rows = 1)
## with helpers
emphasize.cols(1)
emphasize.rows(1)
pandoc.table(t)

emphasize.strong.cells(which(t > 20, arr.ind = TRUE))
pandoc.table(t)

### plain.ascii
pandoc.table(mtcars[1:3, 1:3], plain.ascii = TRUE)

### keep.line.breaks
x <- data.frame(a="Pandoc\nPackage")
pandoc.table(x)
pandoc.table(x, keep.line.breaks = TRUE)

## split.cells
x <- data.frame(a = "foo bar", b = "foo bar")
pandoc.table(x, split.cells = 4)
pandoc.table(x, split.cells = 7)
pandoc.table(x, split.cells = c(4, 7))
pandoc.table(x, split.cells = c("20%", "80%"), split.tables = 30)

y <- c("aa aa aa", "aaa aaa", "a a a a a", "aaaaa", "bbbb bbbb bbbb", "bb bbb bbbb")
y <- matrix(y, ncol = 3, nrow = 2)
rownames(y) <- c("rowname one", "rowname two")
colnames(y) <- c("colname one", "colname two", "colname three")
pandoc.table(y, split.cells = 2)
pandoc.table(y, split.cells = 6)
pandoc.table(y, split.cells = c(2, 6, 10))
pandoc.table(y, split.cells = c(2, Inf, Inf))

## first value used for rownames
pander(y, split.cells = c(5, 2, Inf, Inf))
pandoc.table(y, split.cells = c(5, 2, Inf, 5, 3, 10))

## when not enough reverting to default values
pandoc.table(y, split.cells = c(5, 2))

## split.cells with hyphenation
x <- data.frame(a = "Can be also supplied as a vector, for each cell separately",
       b = "Can be also supplied as a vector, for each cell separately")
pandoc.table(x, split.cells = 10, use.hyphening = TRUE)

pander

An R 'Pandoc' Writer

v0.6.3

AGPL-3 | file LICENSE

Authors

Gergely Daróczi [aut, cre] (<https://orcid.org/0000-0003-3149-8537>), Roman Tsegelskyi [aut]

Initial release

2018-11-06

pandoc.table.return

Description

Usage

Arguments

Details

Value

Note

References

See Also

Examples

pander

We don't support your browser anymore