htmlTable {htmlTable} | R Documentation |
This is a function for outputting a more advanced
table than what xtable, ztable, or knitr's
kable()
allows.
It's aim is to provide the Hmisc latex()
colgroup and rowgroup functions in HTML. The html-output is designed for
maximum compatibility with LibreOffice/OpenOffice.
htmlTable(x, ...) ## Default S3 method: htmlTable(x, header, rnames, rowlabel, caption, tfoot, label, rgroup, n.rgroup, cgroup, n.cgroup, tspanner, n.tspanner, total, align = paste(rep("c", ncol(x)), collapse = ""), align.header = paste(rep("c", ncol(x)), collapse = ""), align.cgroup, css.rgroup = "font-weight: 900;", css.rgroup.sep = "", css.tspanner = "font-weight: 900; text-align: left;", css.tspanner.sep = "border-top: 1px solid #BEBEBE;", css.total = "border-top: 1px solid #BEBEBE; font-weight: 900;", css.cell = "", css.cgroup = "", css.class = "gmisc_table", css.table = "margin-top: 1em; margin-bottom: 1em;", pos.rowlabel = "bottom", pos.caption = "top", col.rgroup = "none", col.columns = "none", padding.rgroup = " ", padding.tspanner = "", ctable = TRUE, compatibility = getOption("htmlTableCompat", "LibreOffice"), cspan.rgroup = "all", ...) ## S3 method for class 'htmlTable' knit_print(x, ...) ## S3 method for class 'htmlTable' print(x, useViewer, ...)
x |
The matrix/data.frame with the data. For the |
... |
Passed on to |
header |
A vector of character strings specifying column
header, defaulting to |
rnames |
Default rownames are generated from |
rowlabel |
If the table has rownames or |
caption |
Adds a table caption. |
tfoot |
Adds a table footer (uses the |
label |
A text string representing a symbolic label for the
table for referencing as an anchor. All you need to do is to reference the
table, for instance |
rgroup |
A vector of character strings containing headings for row groups.
|
n.rgroup |
An integer vector giving the number of rows in each grouping. If |
cgroup |
A vector or a matrix of character strings defining major column header. The default
is to have none. These elements are also known as column spanners. If you want a column not
to have a spanner then put that column as "". If you pass cgroup and |
n.cgroup |
An integer vector or matrix containing the number of columns for which each element in
cgroup is a heading. For example, specify |
tspanner |
The table spanner is somewhat of a table header that you can use when you want to join different tables with the same columns. |
n.tspanner |
An integer vector with the number of rows in the original matrix that the table spanner should span. |
total |
The last row is sometimes a row total with a border on top and
bold fonts. Set this to |
align |
A character strings specifying column alignments, defaulting to
|
align.header |
A character strings specifying alignment for column header,
defaulting to centered, i.e. |
align.cgroup |
The justification of the |
css.rgroup |
CSS style for the rgorup, if different styles are wanted for each of the rgroups you can just specify a vector with the number of elements |
css.rgroup.sep |
The line between different rgroups. The line is set to the TR element of the lower rgroup, i.e. you have to set the border-top/padding-top etc to a line with the expected function. This is only used for rgroups that are printed. You can specify different separators if you give a vector of rgroup - 1 length (this is since the first rgroup doesn't have a separator). |
css.tspanner |
The CSS style for the table spanner |
css.tspanner.sep |
The line between different spanners |
css.total |
The css of the total row |
css.cell |
The css.cell element allows you to add any possible CSS style to your table cells. See section below for details. |
css.cgroup |
The same as |
css.class |
The html CSS class for the table. This allows directing html formatting through CSS directly at all instances of that class. Note: unfortunately the CSS is frequently ignored by word processors. This option is mostly inteded for web-presentations. |
css.table |
You can specify the the style of the table-element using this parameter |
pos.rowlabel |
Where the rowlabel should be positioned. This value can be |
pos.caption |
Set to |
col.rgroup |
Alternating colors (zebra striping/banded rows) for each |
col.columns |
Alternating colors for each column. |
padding.rgroup |
Generally two non-breakings spaces, i.e. |
padding.tspanner |
The table spanner is usually without padding but you may specify padding
similar to |
ctable |
If the table should have a double top border or a single a' la LaTeX ctable style |
compatibility |
Is default set to |
cspan.rgroup |
The number of columns that an |
useViewer |
If you are using RStudio there is a viewer thar can render
the table within that is envoced if in |
string
Returns a string of class htmlTable
cgroup
If you want to have a column spanner in multiple levels you can
set the cgroup
and n.cgroup
arguments to matrices.
If the different levels have different number of elements you
need to set the ones that lack elements to NA. For instance
cgroup = rbind(c("first", "second", NA), c("a", "b", "c"))
.
And the corresponding n,cgroup would be n.cgroup = rbind(c(1, 2, NA), c(2, 1, 2))
.
for a table consisting of 5 columns. The "first" spans the first two columns,
the "second" spans the last three columns, "a" spans the first two, "b"
the middle column, and "c" the last two columns.
rgroup
argumentThe rgroup allows you to smoothly group rows. Each row within a group
receives an indention of two blank spaces and are grouped with their
corresponing rgroup element. The sum(n.rgroup)
should always
be equal or less than the matrix rows. If less then it will pad the
remaining rows with either an empty rgroup, i.e. an "" or if the
rgroup is one longer than the n.rgroup the last n.rgroup element will
be calculated through nrow(x) - sum(n.rgroup)
in order to make
the table generating smoother.
rgroup
You can now have an additional element at the rgroup level by specifying the
attr(rgroup, 'add')
. The value can either be a vector
, a list
,
or a matrix
. See vignette("general", package = "htmlTable")
for examples.
A vector
of either equal number of rgroups to the number
of rgroups that aren't empty, i.e. rgroup[rgroup != ""]
. Or a named vector where
the name must correspond to either an rgroup or to an rgroup number.
A list
that has exactly the same requirements as the vector.
In addition to the previous we can also have a list with column numbers within
as names within the list.
A matrix
with the dimensiont nrow(x) x ncol(x)
or
nrow(x) x 1
where the latter is equivalent to a named vector.
If you have rownames
these will resolve similarly to the names to the
list
/vector
arguments. The same thing applies to colnames
.
This funciton will only work with knitr outputting html, i.e. markdown mode. As the function returns raw html-code the compatibility with non-html formatting is limited, even with pandoc.
Thanks to the the knit_print
and the
asis_output
the results='asis'
is no longer needed except within for-loops.
If you have a knitr-chunk with a for loop and use print()
to produce
raw html you must set the chunk option results='asis'
. Note
:
the print-function relies on the interactive()
function
for determining if the output should be sent to a browser or to the terminal.
In vignettes and other directly knitted documents you may need to either set
useViewer = FALSE
alternatively set options(htmlTable.cat = TRUE)
.
If you set the option table_counter you will get a Table 1,2,3
etc before each table, just set options(table_counter=TRUE)
. If
you set it to a number then that number will correspond to the start of
the table_counter. The table_counter
option will also contain the number
of the last table, this can be useful when referencing it in text. By
setting the option options(table_counter_str = "<b>Table %s:</b> ")
you can manipulate the counter table text that is added prior to the
actual caption. Note, you should use the sprintf
%s
instead of %d
as the software converts all numbers to characters
for compatibility reasons. If you set options(table_counter_roman = TRUE)
then the table counter will use Roman numumerals instead of Arabic.
css.cell
argumentThe css.cell
parameter allows you to add any possible CSS style
to your table cells. css.cell
can be either a vector or a matrix.
If css.cell
is a vector, it's assumed that the styles should be repeated
throughout the columns (that is, each element in css.cell specify the style
for the whole row of 'x').
In the case of css.cell
being a matrix of the same size of the x
argument,
each element of x
gets the style from the corresponding element in css.cell. Additionally,
the number of rows of css.cell
can be nrow(x) + 1
so the first row of of css.cell
specifies the style for the header of x
; also the number of columns of css.cell
can be ncol(x) + 1
to include the specification of style for row names of x
.
Note that the text-align
CSS field in the css.cell
argument will be overriden
by the align
argument.
An empty dataframe will result in a warning and output an empty table, provided that rgroup and n.rgroup are not specified. All other row layout options will be ignored.
Copy-pasting: As you copy-paste results into Word you need to keep the original formatting. Either right click and choose that paste option or click on the icon appearing after a paste. Currently the following compatibitilies have been tested with MS Word 2013:
Internet Explorer (v. 11.20.10586.0) Works perfectly when copy-pasting into Word
RStudio (v. 0.99.448) Works perfectly when copy-pasting into Word. Note: can have issues with multiline cgroups - see bug
Chrome (v. 47.0.2526.106) Works perfectly when copy-pasting into Word. Note: can have issues with multiline cgroups - see bug
Firefox (v. 43.0.3) Works poorly - looses font-styling, lines and general feel
Edge (v. 25.10586.0.0) Works poorly - looses lines and general feel
Direct word processor opening: Opening directly in LibreOffice or Word is no longer recommended. You get much prettier results using the cut-and-paste option.
Note that when using complex cgroup alignments with multiple levels not every browser is able to handle this. For instance the RStudio webkit browser seems to have issues with this and a bug has been filed.
As the table uses html for rendering you need to be aware of that headers,
rownames, and cell values should try respect this for optimal display. Browsers
try to compensate and frequently the tables still turn out fine but it is
not advized. Most importantly you should try to use
<
instead of <
and
>
instead of >
. You can find a complete list
of html characters here.
Other table functions: tblNoLast
,
tblNoNext
# Store all output into a list in order to # output everything at once at the end all_tables <- list() # A simple output output <- matrix(1:4, ncol=2, dimnames = list(list("Row 1", "Row 2"), list("Column 1", "Column 2"))) htmlTable(output) -> all_tables[["Basic table"]] # An advanced output output <- matrix(ncol=6, nrow=8) for (nr in 1:nrow(output)){ for (nc in 1:ncol(output)){ output[nr, nc] <- paste0(nr, ":", nc) } } htmlTable(output, align="r", header = paste(c("1st", "2nd", "3rd", "4th", "5th", "6th"), "hdr"), rnames = paste(c("1st", "2nd", "3rd", paste0(4:8, "th")), "row"), rgroup = paste("Group", LETTERS[1:3]), n.rgroup = c(2,4,nrow(output) - 6), cgroup = rbind(c("", "Column spanners", NA), c("", "Cgroup 1", "Cgroup 2†")), n.cgroup = rbind(c(1,2,NA), c(2,2,2)), caption="Basic table with both column spanners (groups) and row groups", tfoot="† A table footer commment", cspan.rgroup = 2, col.columns = c(rep("none", 2), rep("#F5FBFF", 4)), col.rgroup = c("none", "#F7F7F7"), css.cell = "padding-left: .5em; padding-right: .2em;") -> all_tables[["Advanced table"]] # An advanced empty table output <- matrix(ncol = 6, nrow = 0) htmlTable(output, align="r", header = paste(c("1st", "2nd", "3rd", "4th", "5th", "6th"), "hdr"), cgroup = rbind(c("", "Column spanners", NA), c("", "Cgroup 1", "Cgroup 2†")), n.cgroup = rbind(c(1,2,NA), c(2,2,2)), caption="Basic empty table with column spanners (groups) and ignored row colors", tfoot="† A table footer commment", cspan.rgroup = 2, col.columns = c(rep("none", 2), rep("#F5FBFF", 4)), col.rgroup = c("none", "#F7F7F7"), css.cell = "padding-left: .5em; padding-right: .2em;") -> all_tables[["Empty table"]] # An example of how to use the css.cell for header styling simple_output <- matrix(1:4, ncol=2) htmlTable(simple_output, header = LETTERS[1:2], css.cell = rbind(rep("background: lightgrey; font-size: 2em;", times=ncol(simple_output)), matrix("", ncol=ncol(simple_output), nrow=nrow(simple_output)))) -> all_tables[["Header formatting"]] concatHtmlTables(all_tables) # See vignette("tables", package = "htmlTable") # for more examples