1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/kbl.R
\name{kbl}
\alias{kbl}
\title{Wrapper function of knitr::kable}
\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{
\item{x}{For \code{kable()}, \code{x} is an R object, which is typically a
matrix or data frame. For \code{kables()}, a list with each element being a
returned value from \code{kable()}.}
\item{format}{A character string. Possible values are \code{latex},
\code{html}, \code{pipe} (Pandoc's pipe tables), \code{simple} (Pandoc's
simple tables), \code{rst}, \code{jira}, and \code{org} (Emacs Org-mode).
The value of this argument will be automatically determined if the function
is called within a \pkg{knitr} document. The \code{format} value can also
be set in the global option \code{knitr.table.format}. If \code{format} is
a function, it must return a character string.}
\item{digits}{Maximum number of digits for numeric columns, passed to
\code{round()}. This can also be a vector of length \code{ncol(x)}, to set
the number of digits for individual columns.}
\item{row.names}{Logical: whether to include row names. By default, row names
are included if \code{rownames(x)} is neither \code{NULL} nor identical to
\code{1:nrow(x)}.}
\item{col.names}{A character vector of column names to be used in the table.}
\item{align}{Column alignment: a character vector consisting of \code{'l'}
(left), \code{'c'} (center) and/or \code{'r'} (right). By default or if
\code{align = NULL}, numeric columns are right-aligned, and other columns
are left-aligned. If \code{length(align) == 1L}, the string will be
expanded to a vector of individual letters, e.g. \code{'clc'} becomes
\code{c('c', 'l', 'c')}, unless the output format is LaTeX.}
\item{caption}{The table caption.}
\item{label}{The table reference label. By default, the label is obtained
from \code{knitr::\link[knitr]{opts_current}$get('label')}. To disable the label,
use \code{label = NA}.}
\item{format.args}{A list of arguments to be passed to \code{\link{format}()}
to format table values, e.g. \code{list(big.mark = ',')}.}
\item{escape}{Boolean; whether to escape special characters when producing
HTML or LaTeX tables. When \code{escape = FALSE}, you have to make sure
that special characters will not trigger syntax errors in LaTeX or HTML.}
\item{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"'.}
\item{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.}
\item{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.}
\item{tabular}{The "inner environment" to use for the
table, e.g. "tabularx".}
\item{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 \code{b}, \code{c} and
\code{t} (default).}
\item{position}{This is the "real" or say floating position for the latex
table environment. The \code{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
\code{h} (here), \code{t} (top, default), \code{b} (bottom) and \code{p} (on a dedicated page).}
\item{centering}{T (default)/F. Whether to center tables in the table
environment.}
\item{vline}{vertical separator. Default is nothing for booktabs
tables but "|" for normal tables.}
\item{toprule}{toprule. Default is hline for normal table but toprule for
booktabs tables.}
\item{bottomrule}{bottomrule. Default is hline for normal table but
bottomrule for booktabs tables.}
\item{midrule}{midrule. Default is hline for normal table but midrule for
booktabs tables.}
\item{linesep}{By default, in booktabs tables, \code{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 ''.}
\item{caption.short}{Another latex feature. Short captions for tables}
\item{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.}
\item{...}{Other arguments (see Examples and References).}
}
\description{
The \code{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.
}
\note{
The current set of arguments were written for
\code{knitr} version 1.45. If you are using an older
or newer version, some of the default values may be different.
In \code{knitr::kable()}, the \code{escape} parameter does not affect the text
in the \code{caption} argument, and \code{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 \code{"\\\\\%"}.
}
|
