htmlTable (version 1.0)

htmlTable: Outputting HTML tables

Description

This is a function for outputting a more advanced table than xtable 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.

Usage

htmlTable(x, ...)

## S3 method for class 'default':
htmlTable(x, header, rnames, rowlabel, caption, tfoot, label,
  rgroup, n.rgroup, cgroup, n.cgroup, tspanner, n.tspanner,
  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-transform: capitalize; text-align: left;",
  css.tspanner.sep = "border-top: 1px solid grey;", css.cell = "",
  css.cgroup = "", css.class = "gmisc_table", pos.rowlabel = "bottom",
  pos.caption = "top", col.rgroup = "none", col.columns = "none",
  padding.rgroup = "  ", padding.tspanner = "", ctable = TRUE,
  compatibility = "LibreOffice", cspan.rgroup = "all", ...)

## S3 method for class 'htmlTable':
print(x, useViewer, ...)

Arguments

x

The matrix/data.frame with the data

...

Passed on to print.htmlTable function and any argument except the useViewer will be passed on to the cat functions arguments.

header

A vector of character strings specifying column header, defaulting to colnames(x)

rnames

Default rownames are generated from rownames(x). If you provide FALSE then it will skip the rownames. Note: For data.frames if you do

rowlabel

If the table has rownames or rnames, rowlabel is a character string containing the column heading for the rnames.

caption

Adds a table caption.

tfoot

Adds a table footer (uses the html element). The output is run through txtMergeLines simplifying the generation of multiple lines.

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 see table 2

rgroup

A vector of character strings containing headings for row groups. n.rgroup must be present when rgroup is given. The first n.rgroup[1]rows are sectioned off and rgroup[1] is used as a bold he

n.rgroup

An integer vector giving the number of rows in each grouping. If rgroup is not specified, n.rgroup is just used to divide off blocks of rows by horizontal lines. If rgroup is given but n.rgroup

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

n.cgroup

An integer vector or matrix containing the number of columns for which each element in cgroup is a heading. For example, specify cgroup=c("Major 1","Major 2"), n.cgroup=c(3,3) if "Major 1" is to span colu

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.

align

A character strings specifying column alignments, defaulting to paste(rep('c',ncol(x)),collapse='') to center. Valid alignments are l = left, c = center and r = right. You can also specify

align.header

A character strings specifying alignment for column header, defaulting to centered, i.e. paste(rep('c',ncol(x)),collapse='').

align.cgroup

The justification of the cgroups

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 specif

css.tspanner

The CSS style for the table spanner

css.tspanner.sep

The line between different spanners

css.cell

The css.cell element allows you to add any possible CSS style to your table cells. If you provide a vector the vector it is assummed that the styles should be repeated throughout the columns. If you provide a matrix of the same size as your

css.cgroup

The same as css.class but for cgroup formatting.

css.class

The html CSS class for the table. This allows directing html formatting through http://www.w3schools.com/css/css_selectors.asp{CSS} directly at all instances of that class. Note: unfortunately the CSS is frequently ignore

pos.rowlabel

Where the rowlabel should be positioned. This value can be "top", "bottom", "header", or a integer between 1 and nrow(cgroup) + 1. The options "bottom" and "he

pos.caption

Set to "bottom" to position a caption below the table instead of the default of "top".

col.rgroup

Alternating colors (zebra striping) for each rgroup; one or two colors is recommended and will be recycled.

col.columns

Alternating colors for each column.

padding.rgroup

Generally two non-breakings spaces, i.e.   , but some journals only have a bold face for the rgroup and leaves the subelements unindented.

padding.tspanner

The table spanner is usually without padding but you may specify padding similar to padding.rgroup and it will be added to all elements, including the rgroup elements. This allows for a 3-level hierarchy if needed.

ctable

If the table should have a double top border or a single a' la LaTeX ctable style

compatibility

Is default set to LibreOffice as some settings need to be in old html format as Libre Office can't handle some commands such as the css caption-alignment. Note: this option is not yet fully implemented for all details, in the futu

cspan.rgroup

The number of columns that an rgroup should span. It spans by default all columns but you may want to limit this if you have column colors that you want to retain.

useViewer

If you are using RStudio there is a viewer thar can render the table within that is envoced if in interactive mode. Set this to FALSE if you want to remove that functionality.

Value

• string Returns a string of class htmlTable

Multiple rows of column spanners <code>cgroup</code>

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.

Important <pkg>knitr</pkg>-note

This funciton will only work with knitr outputting html, i.e. markdown mode. For each section where you want a table to be outputted you need to specify: results="asis". As the function returns raw html-code the compatibility with non-html formatting is limited, even with http://johnmacfarlane.net/pandoc/{pandoc}.

Table counter

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 = "Table %s: ") 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.

Possible issues

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 http://code.google.com/p/chromium/issues/detail?id=305130{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 OK 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 http://ascii.cl/htmlcodes.htm{here}.

See Also

txtMergeLines, latex Other table functions: tblNoLast; tblNoNext

Examples

# A simple output
output <- matrix(1:4,
                 ncol=2,
                 dimnames = list(list("Row 1", "Row 2"),
                                 list("Column 1", "Column 2")))
htmlTable(output)

# 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;")

# See vignette("tables", package = "htmlTable")
# for more examples