3 \alias{print.xtableList}
\r
6 Create and Export Lists of Tables
\r
9 \code{xtableList} creates an object which contains information about
\r
10 lists of table which can be used by \code{print.xtableList} to produce
\r
11 a character string which when included in a document produces a nicely
\r
12 formatted table made up of the information in the individual tables
\r
13 which comprised the original list of tables.
\r
16 xtableList(x, caption = NULL, label = NULL,
\r
17 align = NULL, digits = NULL, display = NULL, ...)
\r
19 \method{print}{xtableList}(x,
\r
20 type = getOption("xtable.type", "latex"),
\r
21 file = getOption("xtable.file", ""),
\r
22 append = getOption("xtable.append", FALSE),
\r
23 floating = getOption("xtable.floating", TRUE),
\r
24 floating.environment = getOption("xtable.floating.environment", "table"),
\r
25 table.placement = getOption("xtable.table.placement", "ht"),
\r
26 caption.placement = getOption("xtable.caption.placement", "bottom"),
\r
27 caption.width = getOption("xtable.caption.width", NULL),
\r
28 latex.environments = getOption("xtable.latex.environments", c("center")),
\r
29 tabular.environment = getOption("xtable.tabular.environment", "tabular"),
\r
30 size = getOption("xtable.size", NULL),
\r
32 NA.string = getOption("xtable.NA.string", ""),
\r
33 include.rownames = getOption("xtable.include.rownames", TRUE),
\r
34 colnames.format = "single",
\r
35 only.contents = getOption("xtable.only.contents", FALSE),
\r
37 sanitize.text.function = getOption("xtable.sanitize.text.function", NULL),
\r
38 sanitize.rownames.function = getOption("xtable.sanitize.rownames.function",
\r
39 sanitize.text.function),
\r
40 sanitize.colnames.function = getOption("xtable.sanitize.colnames.function",
\r
41 sanitize.text.function),
\r
42 sanitize.subheadings.function =
\r
43 getOption("xtable.sanitize.subheadings.function",
\r
44 sanitize.text.function),
\r
45 sanitize.message.function =
\r
46 getOption("xtable.sanitize.message.function",
\r
47 sanitize.text.function),
\r
48 math.style.negative = getOption("xtable.math.style.negative", FALSE),
\r
49 math.style.exponents = getOption("xtable.math.style.exponents", FALSE),
\r
50 html.table.attributes = getOption("xtable.html.table.attributes", "border=1"),
\r
51 print.results = getOption("xtable.print.results", TRUE),
\r
52 format.args = getOption("xtable.format.args", NULL),
\r
53 rotate.rownames = getOption("xtable.rotate.rownames", FALSE),
\r
54 rotate.colnames = getOption("xtable.rotate.colnames", FALSE),
\r
55 booktabs = getOption("xtable.booktabs", FALSE),
\r
56 scalebox = getOption("xtable.scalebox", NULL),
\r
57 width = getOption("xtable.width", NULL),
\r
58 comment = getOption("xtable.comment", TRUE),
\r
59 timestamp = getOption("xtable.timestamp", date()),
\r
64 For \code{xtableList}, a list of \R objects all of the same class,
\r
65 being a class found among \code{methods(xtable)}. The list may also
\r
66 have attributes \code{"subheadings"} and \code{"message"}. The
\r
67 attribute \code{"subheadings"} should be a character vector of the
\r
68 same length as the list \code{x}. The attribute \code{"message"}
\r
69 should be a character vector of any length.
\r
70 For \code{print.xtableList}, an object of class \code{xtableList}
\r
71 produced by a call to \code{xtableList}.}
\r
72 \item{caption}{Character vector of length 1 or 2 containing the
\r
73 table's caption or title. If length is 2, the second item is the
\r
74 "short caption" used when LaTeX generates a "List of Tables". Set to
\r
75 \code{NULL} to suppress the caption. Default value is \code{NULL}. }
\r
76 \item{label}{Character vector of length 1 containing the LaTeX label
\r
77 or HTML anchor. Set to \code{NULL} to suppress the label. Default
\r
78 value is \code{NULL}. }
\r
79 \item{align}{Character vector of length equal to the number of columns
\r
80 of the resulting table, indicating the alignment of the corresponding
\r
81 columns. Also, \code{"|"} may be used to produce vertical lines
\r
82 between columns in LaTeX tables, but these are effectively ignored
\r
83 when considering the required length of the supplied vector. If a
\r
84 character vector of length one is supplied, it is split as
\r
85 \code{strsplit(align, "")[[1]]} before processing. Since the row
\r
86 names are printed in the first column, the length of \code{align} is
\r
87 one greater than \code{ncol(x)} if \code{x} is a
\r
88 \code{data.frame}. Use \code{"l"}, \code{"r"}, and \code{"c"} to
\r
89 denote left, right, and center alignment, respectively. Use
\r
90 \code{"p{3cm}"} etc. for a LaTeX column of the specified width. For
\r
91 HTML output the \code{"p"} alignment is interpreted as \code{"l"},
\r
92 ignoring the width request. Default depends on the class of
\r
95 Either \code{NULL}, or a vector of length one, or a vector of length
\r
96 equal to the number of columns in the resulting table, indicating
\r
97 the number of digits to display in the corresponding columns, or a
\r
98 list if length equal to the number of R objects making up \code{x},
\r
99 all members being vectors of the same length, either length one or
\r
100 of length equal to the number of columns in the resulting table. See
\r
101 \sQuote{Details} for further information.}
\r
103 Either \code{NULL}, or a vector of length one, or a vector of length
\r
104 equal to the number of columns in the resulting table, indicating
\r
105 the format of the corresponding columns, or a
\r
106 list if length equal to the number of R objects making up \code{x},
\r
107 all members being vectors of the same length, either length one or
\r
108 of length equal to the number of columns in the resulting table. See
\r
109 \sQuote{Details} for further information.}
\r
110 \item{type}{Type of table to produce. Possible values for \code{type}
\r
111 are \code{"latex"} or \code{"html"}.
\r
112 Default value is \code{"latex"}.}
\r
113 \item{file}{Name of file where the resulting code should be saved. If
\r
114 \code{file=""}, output is displayed on screen. Note that the
\r
115 function also (invisibly) returns a character vector of the results
\r
116 (which can be helpful for post-processing).
\r
117 Default value is \code{""}.}
\r
118 \item{append}{If \code{TRUE} and \code{file!=""}, code will be
\r
119 appended to \code{file} instead of overwriting \code{file}.
\r
120 Default value is \code{FALSE}.}
\r
121 \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting
\r
122 table will be a floating table (using, for example,
\r
123 \code{\\begin\{table\}} and \code{\\end\{table\}}). See
\r
124 \code{floating.environment} below.
\r
125 Default value is \code{TRUE}. }
\r
126 \item{floating.environment}{If \code{floating=TRUE} and
\r
127 \code{type="latex"}, the resulting table uses the specified floating
\r
128 environment. Possible values include \code{"table"}, \code{"table*"},
\r
129 and other floating environments defined in LaTeX packages.
\r
130 Default value is \code{"table"}.}
\r
131 \item{table.placement}{If \code{floating=TRUE} and
\r
132 \code{type="latex"}, the floating table will have placement given by
\r
133 \code{table.placement} where \code{table.placement} must be
\r
134 \code{NULL} or contain only elements of
\r
135 \{"h","t","b","p","!","H"\}.
\r
136 Default value is \code{"ht"}.}
\r
137 \item{caption.placement}{The caption will be placed at the bottom
\r
138 of the table if \code{caption.placement} is \code{"bottom"} and at
\r
139 the top of the table if it equals \code{"top"}.
\r
140 Default value is \code{"bottom"}.}
\r
141 \item{caption.width}{The caption will be placed in a \code{"parbox"}
\r
142 of the specified width if \code{caption.width} is not \code{NULL} and
\r
143 \code{type="latex"}. Default value is \code{NULL}.}
\r
144 \item{latex.environments}{If \code{floating=TRUE} and
\r
145 \code{type="latex"}, the specified LaTeX environments (provided as
\r
146 a character vector) will enclose the tabular environment.
\r
147 Default value is \code{"center"}. }
\r
148 \item{tabular.environment}{When \code{type="latex"}, the tabular
\r
149 environment that will be used.
\r
150 When working with tables that extend more than one page, using
\r
151 \code{tabular.environment="longtable"} with the corresponding
\r
152 LaTeX package (see Fairbairns, 2005) allows one to typeset them
\r
153 uniformly. Note that \code{floating} should be set to
\r
154 \code{FALSE} when using the \code{longtable} environment.
\r
155 Default value is \code{"tabular"}.}
\r
156 \item{size}{A character vector that is inserted just before the
\r
157 tabular environment starts. This can be used to set the font size
\r
158 and a variety of other table settings. Initial backslashes are
\r
159 automatically prefixed, if not supplied by user.
\r
160 Default value is \code{NULL}. }
\r
161 \item{hline.after}{When \code{type="latex"}, a vector of numbers
\r
162 between -1 and the number of rows in the resulting table, inclusive,
\r
163 indicating the rows after which a horizontal line should
\r
164 appear. Determining row numbers is not straightforward since some
\r
165 lines in the resulting table don't enter into the count. The
\r
166 default depends on the value of \code{col.names.format}.}
\r
167 \item{NA.string}{String to be used for missing values in table
\r
169 Default value is \code{""}.}
\r
170 \item{include.rownames}{If \code{TRUE} the rows names are
\r
172 Default value is \code{TRUE}.}
\r
173 \item{colnames.format}{Either \code{"single"} or \code{"multiple"}.
\r
174 Default is \code{"single"}.}
\r
175 \item{only.contents}{If \code{TRUE} only the rows of the
\r
177 Default value is \code{FALSE}. }
\r
178 \item{add.to.row}{A list of two components. The first component (which
\r
179 should be called 'pos') is a list that contains the position of rows on
\r
180 which extra commands should be added at the end. The second
\r
181 component (which should be called 'command') is a character vector
\r
182 of the same length as the first component, which contains the command
\r
183 that should be added at the end of the specified rows.
\r
184 Default value is \code{NULL}, i.e. do not add commands.}
\r
185 \item{sanitize.text.function}{All non-numeric entries (except row and
\r
186 column names) are sanitized in an attempt to remove characters which
\r
187 have special meaning for the output format. If
\r
188 \code{sanitize.text.function} is not \code{NULL}, it should
\r
189 be a function taking a character vector and returning one, and will
\r
190 be used for the sanitization instead of the default internal
\r
192 Default value is \code{NULL}.}
\r
193 \item{sanitize.rownames.function}{Like the
\r
194 \code{sanitize.text.function}, but applicable to row names.
\r
195 The default uses the \code{sanitize.text.function}. }
\r
196 \item{sanitize.colnames.function}{Like the
\r
197 \code{sanitize.text.function}, but applicable to column names.
\r
198 The default uses the \code{sanitize.text.function}. }
\r
199 \item{sanitize.subheadings.function}{Like the
\r
200 \code{sanitize.text.function}, but applicable to subheadings.
\r
201 The default uses the \code{sanitize.text.function}. }
\r
202 \item{sanitize.message.function}{Like the
\r
203 \code{sanitize.text.function}, but applicable to the message.
\r
204 The default uses the \code{sanitize.text.function}. }
\r
205 \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use
\r
206 $-$ for the negative sign (as was the behavior prior to version 1.5-3).
\r
207 Default value is \code{FALSE}.}
\r
208 \item{math.style.exponents}{In a LaTeX table, if \code{TRUE} or
\r
209 \code{"$$"}, then use \verb{$5 \times 10^{5}$} for 5e5. If
\r
210 \code{"ensuremath"}, then use \verb{\\ensuremath{5 \times 10^{5}}}
\r
211 for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to
\r
212 approximate the LaTeX typsetting for 5e5.
\r
213 Default value is \code{FALSE}.}
\r
214 \item{html.table.attributes}{In an HTML table, attributes associated
\r
215 with the \code{<TABLE>} tag.
\r
216 Default value is \code{"border=1"}.}
\r
217 \item{print.results}{If \code{TRUE}, the generated table is printed to
\r
218 standard output. Set this to \code{FALSE} if you will just be using
\r
219 the character vector that is returned invisibly.
\r
220 Default value is \code{TRUE}.}
\r
221 \item{format.args}{List of arguments for the \code{formatC} function.
\r
222 For example, standard German number separators can be specified as
\r
223 \code{format.args=list(big.mark = "'", decimal.mark =
\r
224 ","))}. The arguments \code{digits} and \code{format} should not be
\r
225 included in this list. See details.
\r
226 Default value is \code{NULL}.}
\r
227 \item{rotate.rownames}{If \code{TRUE}, the row names are displayed
\r
228 vertically in LaTeX.
\r
229 Default value is \code{FALSE}.}
\r
230 \item{rotate.colnames}{If \code{TRUE}, the column names are displayed
\r
231 vertically in LaTeX.
\r
232 Default value is \code{FALSE}.}
\r
233 \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and
\r
234 \code{bottomrule} commands from the LaTeX "booktabs" package are used
\r
235 rather than \code{hline} for the horizontal line tags. }
\r
236 \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be
\r
237 added around the tabular environment with the specified value used
\r
238 as the scaling factor.
\r
239 Default value is \code{NULL}.}
\r
240 \item{width}{If not \code{NULL}, the specified value is included in
\r
241 parentheses between the tabular environment \code{begin} tag and the
\r
242 alignment specification. This allows specification of the table
\r
243 width when using tabular environments such as \code{tabular*} and
\r
244 \code{tabularx}. Note that table width specification is not
\r
245 supported with the \code{tabular} or \code{longtable} environments.
\r
246 Default value is \code{NULL}.}
\r
247 \item{comment}{If \code{TRUE}, the version and timestamp comment is
\r
248 included. Default value is \code{TRUE}. }
\r
249 \item{timestamp}{Timestamp to include in LaTeX comment. Set this
\r
250 to \code{NULL} to exclude the timestamp. Default value is
\r
252 \item{\dots}{Additional arguments. (Currently ignored.)}
\r
255 \code{xtableList} produces an object suitable for printing using
\r
256 \code{print.xtableList}.
\r
258 The elements of the list \code{x} supplied to \code{xtableList} must
\r
259 all have the same structure. When these list items are submitted to
\r
260 \code{xtable} the resulting table must have the same number of columns
\r
261 with the same column names and type of data.
\r
263 The values supplied to arguments \code{digits} and \code{display},
\r
264 must be composed of elements as specified in those same arguments for
\r
265 the function \code{\link{xtable}}. See the help for
\r
266 \code{\link{xtable}} for details.
\r
268 \code{print.xtableList} produces tables in two different formats
\r
269 depending on the value of \code{col.names.format}. If
\r
270 \code{col.names.format = "single"}, the resulting table has only a
\r
271 single heading row. If \code{col.names.format = "multiple"} there is a
\r
272 heading row for each of the subtables making up the complete table.
\r
274 By default if \code{col.names.format = "single"}, there are horizontal
\r
275 lines above and below the heading row, and at the end of each
\r
276 subtable. If \code{col.names.format = "multiple"}, there are
\r
277 horizontal lines above and below each appearance of the heading row,
\r
278 and at the end of each subtable.
\r
280 If \code{"subheadings"} is not \code{NULL}, the individual elements of
\r
281 this vector (which can include newlines \verb{\\n}) produce a heading
\r
282 line or lines for the subtables. When \code{col.names.format =
\r
283 "multiple"} these subheadings appear \emph{above} the heading rows.
\r
285 If \code{"message"} is not \code{NULL} the vector produces a line or
\r
286 lines at the end of the table.
\r
288 Consult the vignette \sQuote{The \code{xtableList} Gallery} to see
\r
289 the behaviour of these functions.
\r
291 Note that at present there is no code for \code{type = "html"}.
\r
294 \code{xtableList} produces an object of class
\r
295 \code{"xtableList"}. An object of this class is a list of
\r
296 \code{"xtable"} objects with some additional attributes. Each element
\r
297 of the list can have a \code{"subheading"} attribute. The list can
\r
298 also have a \code{"message"} attribute.
\r
300 \code{print.xtableList} produces a character string containing LaTeX
\r
301 markup which produces a nicely formatted table comprised of subtables,
\r
302 when included in a LaTeX document.
\r
305 David Scott \email{d.scott@auckland.ac.nz}.
\r
308 The functions \code{xtableList} and \code{print.xtableList} are
\r
309 new and their behaviour may change in the future based on user
\r
310 experience and recommendations.
\r
315 \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}},
\r
316 \code{\link{align}}, \code{\link{digits}}, \code{\link{display}},
\r
317 \code{\link{formatC}}, \code{\link{print.xtable}}.
\r
321 mtcars <- mtcars[, 1:6]
\r
322 mtcarsList <- split(mtcars, f = mtcars$cyl)
\r
323 attr(mtcarsList, "subheadings") <- paste0("Number of cylinders = ",
\r
325 attr(mtcarsList, "message") <- c("Line 1 of Message",
\r
326 "Line 2 of Message")
\r
327 xList <- xtableList(mtcarsList)
\r
328 print.xtableList(xList)
\r
329 print.xtableList(xList, colnames.format = "multiple")
\r
projects / xtable.git / blob