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
63 \item{x}{For \code{xtableList}, a list of \R objects all of the same
\r
64 class, being a class found among \code{methods(xtable)}.
\r
65 For \code{print.xtableList}, an object of class \code{xtableList}
\r
66 produced by a call to \code{xtableList}.}
\r
67 \item{caption}{Character vector of length 1 or 2 containing the
\r
68 table's caption or title. If length is 2, the second item is the
\r
69 "short caption" used when LaTeX generates a "List of Tables". Set to
\r
70 \code{NULL} to suppress the caption. Default value is \code{NULL}. }
\r
71 \item{label}{Character vector of length 1 containing the LaTeX label
\r
72 or HTML anchor. Set to \code{NULL} to suppress the label. Default
\r
73 value is \code{NULL}. }
\r
74 \item{align}{Character vector of length equal to the number of columns
\r
75 of the resulting table, indicating the alignment of the corresponding
\r
76 columns. Also, \code{"|"} may be used to produce vertical lines
\r
77 between columns in LaTeX tables, but these are effectively ignored
\r
78 when considering the required length of the supplied vector. If a
\r
79 character vector of length one is supplied, it is split as
\r
80 \code{strsplit(align, "")[[1]]} before processing. Since the row
\r
81 names are printed in the first column, the length of \code{align} is
\r
82 one greater than \code{ncol(x)} if \code{x} is a
\r
83 \code{data.frame}. Use \code{"l"}, \code{"r"}, and \code{"c"} to
\r
84 denote left, right, and center alignment, respectively. Use
\r
85 \code{"p{3cm}"} etc. for a LaTeX column of the specified width. For
\r
86 HTML output the \code{"p"} alignment is interpreted as \code{"l"},
\r
87 ignoring the width request. Default depends on the class of
\r
90 Either \code{NULL}, or a vector of length one, or a vector of length
\r
91 equal to the number of columns in the resulting table, indicating
\r
92 the number of digits to display in the corresponding columns, or a
\r
93 list if length equal to the number of R objects making up \code{x},
\r
94 all members being vectors of the same length, either length one or
\r
95 of length equal to the number of columns in the resulting table. See
\r
96 \sQuote{Details} for further information.}
\r
98 Either \code{NULL}, or a vector of length one, or a vector of length
\r
99 equal to the number of columns in the resulting table, indicating
\r
100 the format of the corresponding columns, or a
\r
101 list if length equal to the number of R objects making up \code{x},
\r
102 all members being vectors of the same length, either length one or
\r
103 of length equal to the number of columns in the resulting table. See
\r
104 \sQuote{Details} for further information.}
\r
105 \item{type}{Type of table to produce. Possible values for \code{type}
\r
106 are \code{"latex"} or \code{"html"}.
\r
107 Default value is \code{"latex"}.}
\r
108 \item{file}{Name of file where the resulting code should be saved. If
\r
109 \code{file=""}, output is displayed on screen. Note that the
\r
110 function also (invisibly) returns a character vector of the results
\r
111 (which can be helpful for post-processing).
\r
112 Default value is \code{""}.}
\r
113 \item{append}{If \code{TRUE} and \code{file!=""}, code will be
\r
114 appended to \code{file} instead of overwriting \code{file}.
\r
115 Default value is \code{FALSE}.}
\r
116 \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting
\r
117 table will be a floating table (using, for example,
\r
118 \code{\\begin\{table\}} and \code{\\end\{table\}}). See
\r
119 \code{floating.environment} below.
\r
120 Default value is \code{TRUE}. }
\r
121 \item{floating.environment}{If \code{floating=TRUE} and
\r
122 \code{type="latex"}, the resulting table uses the specified floating
\r
123 environment. Possible values include \code{"table"}, \code{"table*"},
\r
124 and other floating environments defined in LaTeX packages.
\r
125 Default value is \code{"table"}.}
\r
126 \item{table.placement}{If \code{floating=TRUE} and
\r
127 \code{type="latex"}, the floating table will have placement given by
\r
128 \code{table.placement} where \code{table.placement} must be
\r
129 \code{NULL} or contain only elements of
\r
130 \{"h","t","b","p","!","H"\}.
\r
131 Default value is \code{"ht"}.}
\r
132 \item{caption.placement}{The caption will be placed at the bottom
\r
133 of the table if \code{caption.placement} is \code{"bottom"} and at
\r
134 the top of the table if it equals \code{"top"}.
\r
135 Default value is \code{"bottom"}.}
\r
136 \item{caption.width}{The caption will be placed in a \code{"parbox"}
\r
137 of the specified width if \code{caption.width} is not \code{NULL} and
\r
138 \code{type="latex"}. Default value is \code{NULL}.}
\r
139 \item{latex.environments}{If \code{floating=TRUE} and
\r
140 \code{type="latex"}, the specified LaTeX environments (provided as
\r
141 a character vector) will enclose the tabular environment.
\r
142 Default value is \code{"center"}. }
\r
143 \item{tabular.environment}{When \code{type="latex"}, the tabular
\r
144 environment that will be used.
\r
145 When working with tables that extend more than one page, using
\r
146 \code{tabular.environment="longtable"} with the corresponding
\r
147 LaTeX package (see Fairbairns, 2005) allows one to typeset them
\r
148 uniformly. Note that \code{floating} should be set to
\r
149 \code{FALSE} when using the \code{longtable} environment.
\r
150 Default value is \code{"tabular"}.}
\r
151 \item{size}{A character vector that is inserted just before the
\r
152 tabular environment starts. This can be used to set the font size
\r
153 and a variety of other table settings. Initial backslashes are
\r
154 automatically prefixed, if not supplied by user.
\r
155 Default value is \code{NULL}. }
\r
156 \item{hline.after}{When \code{type="latex"}, a vector of numbers
\r
157 between -1 and the number of rows in the resulting table, inclusive,
\r
158 indicating the rows after which a horizontal line should
\r
159 appear. Determining row numbers is not straightforward since some
\r
160 lines in the resulting table don't enter into the count. The
\r
161 default depends on the value of \code{col.names.format}.}
\r
162 \item{NA.string}{String to be used for missing values in table
\r
164 Default value is \code{""}.}
\r
165 \item{include.rownames}{If \code{TRUE} the rows names are
\r
167 Default value is \code{TRUE}.}
\r
168 \item{colnames.format}{Either \code{"single"} or \code{"multiple"}.
\r
169 Default is \code{"single"}.}
\r
170 \item{only.contents}{If \code{TRUE} only the rows of the
\r
172 Default value is \code{FALSE}. }
\r
173 \item{add.to.row}{A list of two components. The first component (which
\r
174 should be called 'pos') is a list that contains the position of rows on
\r
175 which extra commands should be added at the end. The second
\r
176 component (which should be called 'command') is a character vector
\r
177 of the same length as the first component, which contains the command
\r
178 that should be added at the end of the specified rows.
\r
179 Default value is \code{NULL}, i.e. do not add commands.}
\r
180 \item{sanitize.text.function}{All non-numeric entries (except row and
\r
181 column names) are sanitized in an attempt to remove characters which
\r
182 have special meaning for the output format. If
\r
183 \code{sanitize.text.function} is not \code{NULL}, it should
\r
184 be a function taking a character vector and returning one, and will
\r
185 be used for the sanitization instead of the default internal
\r
187 Default value is \code{NULL}.}
\r
188 \item{sanitize.rownames.function}{Like the
\r
189 \code{sanitize.text.function}, but applicable to row names.
\r
190 The default uses the \code{sanitize.text.function}. }
\r
191 \item{sanitize.colnames.function}{Like the
\r
192 \code{sanitize.text.function}, but applicable to column names.
\r
193 The default uses the \code{sanitize.text.function}. }
\r
194 \item{sanitize.subheadings.function}{Like the
\r
195 \code{sanitize.text.function}, but applicable to subheadings.
\r
196 The default uses the \code{sanitize.text.function}. }
\r
197 \item{sanitize.message.function}{Like the
\r
198 \code{sanitize.text.function}, but applicable to the message.
\r
199 The default uses the \code{sanitize.text.function}. }
\r
200 \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use
\r
201 $-$ for the negative sign (as was the behavior prior to version 1.5-3).
\r
202 Default value is \code{FALSE}.}
\r
203 \item{math.style.exponents}{In a LaTeX table, if \code{TRUE} or
\r
204 \code{"$$"}, then use \verb{$5 \times 10^{5}$} for 5e5. If
\r
205 \code{"ensuremath"}, then use \verb{\\ensuremath{5 \times 10^{5}}}
\r
206 for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to
\r
207 approximate the LaTeX typsetting for 5e5.
\r
208 Default value is \code{FALSE}.}
\r
209 \item{html.table.attributes}{In an HTML table, attributes associated
\r
210 with the \code{<TABLE>} tag.
\r
211 Default value is \code{"border=1"}.}
\r
212 \item{print.results}{If \code{TRUE}, the generated table is printed to
\r
213 standard output. Set this to \code{FALSE} if you will just be using
\r
214 the character vector that is returned invisibly.
\r
215 Default value is \code{TRUE}.}
\r
216 \item{format.args}{List of arguments for the \code{formatC} function.
\r
217 For example, standard German number separators can be specified as
\r
218 \code{format.args=list(big.mark = "'", decimal.mark =
\r
219 ","))}. The arguments \code{digits} and \code{format} should not be
\r
220 included in this list. See details.
\r
221 Default value is \code{NULL}.}
\r
222 \item{rotate.rownames}{If \code{TRUE}, the row names are displayed
\r
223 vertically in LaTeX.
\r
224 Default value is \code{FALSE}.}
\r
225 \item{rotate.colnames}{If \code{TRUE}, the column names are displayed
\r
226 vertically in LaTeX.
\r
227 Default value is \code{FALSE}.}
\r
228 \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and
\r
229 \code{bottomrule} commands from the LaTeX "booktabs" package are used
\r
230 rather than \code{hline} for the horizontal line tags. }
\r
231 \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be
\r
232 added around the tabular environment with the specified value used
\r
233 as the scaling factor.
\r
234 Default value is \code{NULL}.}
\r
235 \item{width}{If not \code{NULL}, the specified value is included in
\r
236 parentheses between the tabular environment \code{begin} tag and the
\r
237 alignment specification. This allows specification of the table
\r
238 width when using tabular environments such as \code{tabular*} and
\r
239 \code{tabularx}. Note that table width specification is not
\r
240 supported with the \code{tabular} or \code{longtable} environments.
\r
241 Default value is \code{NULL}.}
\r
242 \item{comment}{If \code{TRUE}, the version and timestamp comment is
\r
243 included. Default value is \code{TRUE}. }
\r
244 \item{timestamp}{Timestamp to include in LaTeX comment. Set this
\r
245 to \code{NULL} to exclude the timestamp. Default value is
\r
247 \item{\dots}{Additional arguments. (Currently ignored.)}
\r
250 %% ~~ If necessary, more details than the description above ~~
\r
253 %% ~Describe the value returned
\r
254 %% If it is a LIST, use
\r
255 %% \item{comp1 }{Description of 'comp1'}
\r
256 %% \item{comp2 }{Description of 'comp2'}
\r
260 David Scott \email{d.scott@auckland.ac.nz}.
\r
263 The functions \code{xtableList} and \code{print.xtableList} are
\r
264 new and their behaviour may change in the future based on user
\r
265 experience and recommendations.
\r
270 \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}},
\r
271 \code{\link{align}}, \code{\link{digits}}, \code{\link{display}},
\r
272 \code{\link{formatC}}
\r