\name{xtableList} \alias{xtableList} \alias{print.xtableList} \title{ Create and Export Lists of Tables } \description{ \code{xtableList} creates an object which contains information about lists of table which can be used by \code{print.xtableList} to produce a character string which when included in a document produces a nicely formatted table made up of the information in the individual tables which comprised the original list of tables. } \usage{ xtableList(x, caption = NULL, label = NULL, align = NULL, digits = NULL, display = NULL, ...) \method{print}{xtableList}(x, type = getOption("xtable.type", "latex"), file = getOption("xtable.file", ""), append = getOption("xtable.append", FALSE), floating = getOption("xtable.floating", TRUE), floating.environment = getOption("xtable.floating.environment", "table"), table.placement = getOption("xtable.table.placement", "ht"), caption.placement = getOption("xtable.caption.placement", "bottom"), caption.width = getOption("xtable.caption.width", NULL), latex.environments = getOption("xtable.latex.environments", c("center")), tabular.environment = getOption("xtable.tabular.environment", "tabular"), size = getOption("xtable.size", NULL), hline.after = NULL, NA.string = getOption("xtable.NA.string", ""), include.rownames = getOption("xtable.include.rownames", TRUE), colnames.format = "single", only.contents = getOption("xtable.only.contents", FALSE), add.to.row = NULL, sanitize.text.function = getOption("xtable.sanitize.text.function", NULL), sanitize.rownames.function = getOption("xtable.sanitize.rownames.function", sanitize.text.function), sanitize.colnames.function = getOption("xtable.sanitize.colnames.function", sanitize.text.function), sanitize.subheadings.function = getOption("xtable.sanitize.subheadings.function", sanitize.text.function), sanitize.message.function = getOption("xtable.sanitize.message.function", sanitize.text.function), math.style.negative = getOption("xtable.math.style.negative", FALSE), math.style.exponents = getOption("xtable.math.style.exponents", FALSE), html.table.attributes = getOption("xtable.html.table.attributes", "border=1"), print.results = getOption("xtable.print.results", TRUE), format.args = getOption("xtable.format.args", NULL), rotate.rownames = getOption("xtable.rotate.rownames", FALSE), rotate.colnames = getOption("xtable.rotate.colnames", FALSE), booktabs = getOption("xtable.booktabs", FALSE), scalebox = getOption("xtable.scalebox", NULL), width = getOption("xtable.width", NULL), comment = getOption("xtable.comment", TRUE), timestamp = getOption("xtable.timestamp", date()), ...) } \arguments{ \item{x}{ For \code{xtableList}, a list of \R objects all of the same class, being a class found among \code{methods(xtable)}. The list may also have attributes \code{"subheadings"} and \code{"message"}. The attribute \code{"subheadings"} should be a character vector of the same length as the list \code{x}. The attribute \code{"message"} should be a character vector of any length. For \code{print.xtableList}, an object of class \code{xtableList} produced by a call to \code{xtableList}.} \item{caption}{Character vector of length 1 or 2 containing the table's caption or title. If length is 2, the second item is the "short caption" used when LaTeX generates a "List of Tables". Set to \code{NULL} to suppress the caption. Default value is \code{NULL}. } \item{label}{Character vector of length 1 containing the LaTeX label or HTML anchor. Set to \code{NULL} to suppress the label. Default value is \code{NULL}. } \item{align}{Character vector of length equal to the number of columns of the resulting table, indicating the alignment of the corresponding columns. Also, \code{"|"} may be used to produce vertical lines between columns in LaTeX tables, but these are effectively ignored when considering the required length of the supplied vector. If a character vector of length one is supplied, it is split as \code{strsplit(align, "")[[1]]} before processing. Since the row names are printed in the first column, the length of \code{align} is one greater than \code{ncol(x)} if \code{x} is a \code{data.frame}. Use \code{"l"}, \code{"r"}, and \code{"c"} to denote left, right, and center alignment, respectively. Use \code{"p{3cm}"} etc. for a LaTeX column of the specified width. For HTML output the \code{"p"} alignment is interpreted as \code{"l"}, ignoring the width request. Default depends on the class of \code{x}. } \item{digits}{ Either \code{NULL}, or a vector of length one, or a vector of length equal to the number of columns in the resulting table, indicating the number of digits to display in the corresponding columns, or a list if length equal to the number of R objects making up \code{x}, all members being vectors of the same length, either length one or of length equal to the number of columns in the resulting table. See \sQuote{Details} for further information.} \item{display}{ Either \code{NULL}, or a vector of length one, or a vector of length equal to the number of columns in the resulting table, indicating the format of the corresponding columns, or a list if length equal to the number of R objects making up \code{x}, all members being vectors of the same length, either length one or of length equal to the number of columns in the resulting table. See \sQuote{Details} for further information.} \item{type}{Type of table to produce. Possible values for \code{type} are \code{"latex"} or \code{"html"}. Default value is \code{"latex"}.} \item{file}{Name of file where the resulting code should be saved. If \code{file=""}, output is displayed on screen. Note that the function also (invisibly) returns a character vector of the results (which can be helpful for post-processing). Default value is \code{""}.} \item{append}{If \code{TRUE} and \code{file!=""}, code will be appended to \code{file} instead of overwriting \code{file}. Default value is \code{FALSE}.} \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting table will be a floating table (using, for example, \code{\\begin\{table\}} and \code{\\end\{table\}}). See \code{floating.environment} below. Default value is \code{TRUE}. } \item{floating.environment}{If \code{floating=TRUE} and \code{type="latex"}, the resulting table uses the specified floating environment. Possible values include \code{"table"}, \code{"table*"}, and other floating environments defined in LaTeX packages. Default value is \code{"table"}.} \item{table.placement}{If \code{floating=TRUE} and \code{type="latex"}, the floating table will have placement given by \code{table.placement} where \code{table.placement} must be \code{NULL} or contain only elements of \{"h","t","b","p","!","H"\}. Default value is \code{"ht"}.} \item{caption.placement}{The caption will be placed at the bottom of the table if \code{caption.placement} is \code{"bottom"} and at the top of the table if it equals \code{"top"}. Default value is \code{"bottom"}.} \item{caption.width}{The caption will be placed in a \code{"parbox"} of the specified width if \code{caption.width} is not \code{NULL} and \code{type="latex"}. Default value is \code{NULL}.} \item{latex.environments}{If \code{floating=TRUE} and \code{type="latex"}, the specified LaTeX environments (provided as a character vector) will enclose the tabular environment. Default value is \code{"center"}. } \item{tabular.environment}{When \code{type="latex"}, the tabular environment that will be used. When working with tables that extend more than one page, using \code{tabular.environment="longtable"} with the corresponding LaTeX package (see Fairbairns, 2005) allows one to typeset them uniformly. Note that \code{floating} should be set to \code{FALSE} when using the \code{longtable} environment. Default value is \code{"tabular"}.} \item{size}{A character vector that is inserted just before the tabular environment starts. This can be used to set the font size and a variety of other table settings. Initial backslashes are automatically prefixed, if not supplied by user. Default value is \code{NULL}. } \item{hline.after}{When \code{type="latex"}, a vector of numbers between -1 and the number of rows in the resulting table, inclusive, indicating the rows after which a horizontal line should appear. Determining row numbers is not straightforward since some lines in the resulting table don't enter into the count. The default depends on the value of \code{col.names.format}.} \item{NA.string}{String to be used for missing values in table entries. Default value is \code{""}.} \item{include.rownames}{If \code{TRUE} the rows names are printed. Default value is \code{TRUE}.} \item{colnames.format}{Either \code{"single"} or \code{"multiple"}. Default is \code{"single"}.} \item{only.contents}{If \code{TRUE} only the rows of the table are printed. Default value is \code{FALSE}. } \item{add.to.row}{A list of two components. The first component (which should be called 'pos') is a list that contains the position of rows on which extra commands should be added at the end. The second component (which should be called 'command') is a character vector of the same length as the first component, which contains the command that should be added at the end of the specified rows. Default value is \code{NULL}, i.e. do not add commands.} \item{sanitize.text.function}{All non-numeric entries (except row and column names) are sanitized in an attempt to remove characters which have special meaning for the output format. If \code{sanitize.text.function} is not \code{NULL}, it should be a function taking a character vector and returning one, and will be used for the sanitization instead of the default internal function. Default value is \code{NULL}.} \item{sanitize.rownames.function}{Like the \code{sanitize.text.function}, but applicable to row names. The default uses the \code{sanitize.text.function}. } \item{sanitize.colnames.function}{Like the \code{sanitize.text.function}, but applicable to column names. The default uses the \code{sanitize.text.function}. } \item{sanitize.subheadings.function}{Like the \code{sanitize.text.function}, but applicable to subheadings. The default uses the \code{sanitize.text.function}. } \item{sanitize.message.function}{Like the \code{sanitize.text.function}, but applicable to the message. The default uses the \code{sanitize.text.function}. } \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use $-$ for the negative sign (as was the behavior prior to version 1.5-3). Default value is \code{FALSE}.} \item{math.style.exponents}{In a LaTeX table, if \code{TRUE} or \code{"$$"}, then use \verb{$5 \times 10^{5}$} for 5e5. If \code{"ensuremath"}, then use \verb{\\ensuremath{5 \times 10^{5}}} for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to approximate the LaTeX typsetting for 5e5. Default value is \code{FALSE}.} \item{html.table.attributes}{In an HTML table, attributes associated with the \code{} tag. Default value is \code{"border=1"}.} \item{print.results}{If \code{TRUE}, the generated table is printed to standard output. Set this to \code{FALSE} if you will just be using the character vector that is returned invisibly. Default value is \code{TRUE}.} \item{format.args}{List of arguments for the \code{formatC} function. For example, standard German number separators can be specified as \code{format.args=list(big.mark = "'", decimal.mark = ","))}. The arguments \code{digits} and \code{format} should not be included in this list. See details. Default value is \code{NULL}.} \item{rotate.rownames}{If \code{TRUE}, the row names are displayed vertically in LaTeX. Default value is \code{FALSE}.} \item{rotate.colnames}{If \code{TRUE}, the column names are displayed vertically in LaTeX. Default value is \code{FALSE}.} \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and \code{bottomrule} commands from the LaTeX "booktabs" package are used rather than \code{hline} for the horizontal line tags. } \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be added around the tabular environment with the specified value used as the scaling factor. Default value is \code{NULL}.} \item{width}{If not \code{NULL}, the specified value is included in parentheses between the tabular environment \code{begin} tag and the alignment specification. This allows specification of the table width when using tabular environments such as \code{tabular*} and \code{tabularx}. Note that table width specification is not supported with the \code{tabular} or \code{longtable} environments. Default value is \code{NULL}.} \item{comment}{If \code{TRUE}, the version and timestamp comment is included. Default value is \code{TRUE}. } \item{timestamp}{Timestamp to include in LaTeX comment. Set this to \code{NULL} to exclude the timestamp. Default value is \code{date()}. } \item{\dots}{Additional arguments. (Currently ignored.)} } \details{ \code{xtableList} produces an object suitable for printing using \code{print.xtableList}. The elements of the list \code{x} supplied to \code{xtableList} must all have the same structure. When these list items are submitted to \code{xtable} the resulting table must have the same number of columns with the same column names and type of data. The values supplied to arguments \code{digits} and \code{display}, must be composed of elements as specified in those same arguments for the function \code{\link{xtable}}. See the help for \code{\link{xtable}} for details. \code{print.xtableList} produces tables in two different formats depending on the value of \code{col.names.format}. If \code{col.names.format = "single"}, the resulting table has only a single heading row. If \code{col.names.format = "multiple"} there is a heading row for each of the subtables making up the complete table. By default if \code{col.names.format = "single"}, there are horizontal lines above and below the heading row, and at the end of each subtable. If \code{col.names.format = "multiple"}, there are horizontal lines above and below each appearance of the heading row, and at the end of each subtable. If \code{"subheadings"} is not \code{NULL}, the individual elements of this vector (which can include newlines \verb{\\n}) produce a heading line or lines for the subtables. When \code{col.names.format = "multiple"} these subheadings appear \emph{above} the heading rows. If \code{"message"} is not \code{NULL} the vector produces a line or lines at the end of the table. Consult the vignette \sQuote{The \code{xtableList} Gallery} to see the behaviour of these functions. Note that at present there is no code for \code{type = "html"}. } \value{ \code{xtableList} produces an object of class \code{"xtableList"}. An object of this class is a list of \code{"xtable"} objects with some additional attributes. Each element of the list can have a \code{"subheading"} attribute. The list can also have a \code{"message"} attribute. \code{print.xtableList} produces a character string containing LaTeX markup which produces a nicely formatted table comprised of subtables, when included in a LaTeX document. } \author{ David Scott \email{d.scott@auckland.ac.nz}. } \note{ The functions \code{xtableList} and \code{print.xtableList} are new and their behaviour may change in the future based on user experience and recommendations. } \seealso{ \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}}, \code{\link{align}}, \code{\link{digits}}, \code{\link{display}}, \code{\link{formatC}}, \code{\link{print.xtable}}. } \examples{ data(mtcars) mtcars <- mtcars[, 1:6] mtcarsList <- split(mtcars, f = mtcars$cyl) attr(mtcarsList, "subheadings") <- paste0("Number of cylinders = ", names(mtcarsList)) attr(mtcarsList, "message") <- c("Line 1 of Message", "Line 2 of Message") xList <- xtableList(mtcarsList) print.xtableList(xList) print.xtableList(xList, colnames.format = "multiple") } \keyword{ print }