kbl {kableExtra}

Wrapper function of knitr::kable

Description

The knitr::kable() function is the foundation of this package. However, it has many latex/html specific arguments hidden under the ground unless you check its source code. This wrapper function is created to provide better documentation (and auto-complete yay) and at the same time, solve the auto format setting in a better way.

Usage

kbl(
  x,
  format,
  digits = getOption("digits"),
  row.names = NA,
  col.names = NA,
  align,
  caption = NULL,
  label = NULL,
  format.args = list(),
  escape = TRUE,
  table.attr = getOption("knitr.table.html.attr", ""),
  booktabs = FALSE,
  longtable = FALSE,
  tabular = if (longtable) "longtable" else "tabular",
  valign = if (tabular %in% c("tabularx", "xltabular")) "{\\linewidth}" else "[t]",
  position = "",
  centering = TRUE,
  vline = getOption("knitr.table.vline", if (booktabs) "" else "|"),
  toprule = getOption("knitr.table.toprule", if (booktabs) "\\toprule" else
    "\\hline"),
  bottomrule = getOption("knitr.table.bottomrule", if (booktabs) "\\bottomrule" else
    "\\hline"),
  midrule = getOption("knitr.table.midrule", if (booktabs) "\\midrule" else
    "\\hline"),
  linesep = if (booktabs) c("", "", "", "", "\\addlinespace") else "\\hline",
  caption.short = "",
  table.envir = if (!is.null(caption)) "table",
  ...
)

Arguments

x

For kable(), x is an R object, which is typically a matrix or data frame. For kables(), a list with each element being a returned value from kable().

format

A character string. Possible values are latex, html, pipe (Pandoc's pipe tables), simple (Pandoc's simple tables), rst, jira, and org (Emacs Org-mode). The value of this argument will be automatically determined if the function is called within a knitr document. The format value can also be set in the global option knitr.table.format. If format is a function, it must return a character string.

digits

Maximum number of digits for numeric columns, passed to round(). This can also be a vector of length ncol(x), to set the number of digits for individual columns.

row.names

Logical: whether to include row names. By default, row names are included if rownames(x) is neither NULL nor identical to 1:nrow(x).

col.names

A character vector of column names to be used in the table.

align

Column alignment: a character vector consisting of 'l' (left), 'c' (center) and/or 'r' (right). By default or if align = NULL, numeric columns are right-aligned, and other columns are left-aligned. If length(align) == 1L, the string will be expanded to a vector of individual letters, e.g. 'clc' becomes c('c', 'l', 'c'), unless the output format is LaTeX.

caption

The table caption.

label

The table reference label. By default, the label is obtained from knitr::opts_current$get('label'). To disable the label, use label = NA.

format.args

A list of arguments to be passed to format() to format table values, e.g. list(big.mark = ',').

escape

Boolean; whether to escape special characters when producing HTML or LaTeX tables. When escape = FALSE, you have to make sure that special characters will not trigger syntax errors in LaTeX or HTML.

table.attr

A character string for addition HTML table attributes. This is convenient if you simply want to add a few HTML classes or styles. For example, you can put 'class="table" style="color: red"'.

booktabs

T/F for whether to enable the booktabs format for tables. I personally would recommend you turn this on for every latex table except some special cases.

longtable

T/F for whether to use the longtable format. If you have a table that will span over two or more pages, you will have to turn this on.

tabular

The "inner environment" to use for the table, e.g. "tabularx".

valign

You probably won't need to adjust this latex option very often. If you are familiar with latex tables, this is the optional position for the tabular environment controlling the vertical position of the table relative to the baseline of the surrounding text. Possible choices are b, c and t (default).

position

This is the "real" or say floating position for the latex table environment. The kable only puts tables in a table environment when a caption is provided. That is also the reason why your tables will be floating around if you specify captions for your table. Possible choices are h (here), t (top, default), b (bottom) and p (on a dedicated page).

centering

T (default)/F. Whether to center tables in the table environment.

vline

vertical separator. Default is nothing for booktabs tables but "|" for normal tables.

toprule

toprule. Default is hline for normal table but toprule for booktabs tables.

bottomrule

bottomrule. Default is hline for normal table but bottomrule for booktabs tables.

midrule

midrule. Default is hline for normal table but midrule for booktabs tables.

linesep

By default, in booktabs tables, kable insert an extra space every five rows for clear display. If you don't want this feature or if you want to do it in a different pattern, you can consider change this option. The default is c(”, ”, ”, ”, '\addlinespace'). Also, if you are not using booktabs, but you want a cleaner display, you can change this to ”.

caption.short

Another latex feature. Short captions for tables

table.envir

You probably don't need to change this as well. The default setting is to put a table environment outside of tabular if a caption is provided.

...

Other arguments (see Examples and References).

Note

The current set of arguments were written for knitr version 1.45. If you are using an older or newer version, some of the default values may be different.

In knitr::kable(), the escape parameter does not affect the text in the caption argument, and kbl() inherits this behavior. This means that special characters in the caption (such as "%" for LaTeX output) need to be escaped by the user, e.g. written as "\\%".