3 \alias{print.xtableFtable}
6 Create and Export Flat Tables
9 \code{xtableFtable} creates an object which contains information about
10 a flat table which can be used by \code{print.xtableFtable} to produce
11 a character string which when included in a document produces a nicely
15 xtableFtable(x, caption = NULL, label = NULL,
16 align = NULL, digits = 0, display = NULL,
18 method = c("non.compact", "row.compact",
19 "col.compact", "compact"),
22 \method{print}{xtableFtable}(x,
23 type = getOption("xtable.type", "latex"),
24 file = getOption("xtable.file", ""),
25 append = getOption("xtable.append", FALSE),
26 floating = getOption("xtable.floating", TRUE),
27 floating.environment = getOption("xtable.floating.environment", "table"),
28 table.placement = getOption("xtable.table.placement", "ht"),
29 caption.placement = getOption("xtable.caption.placement", "bottom"),
30 caption.width = getOption("xtable.caption.width", NULL),
31 latex.environments = getOption("xtable.latex.environments", c("center")),
32 tabular.environment = getOption("xtable.tabular.environment", "tabular"),
33 size = getOption("xtable.size", NULL),
34 hline.after = getOption("xtable.hline.after", NULL),
35 NA.string = getOption("xtable.NA.string", ""),
36 only.contents = getOption("xtable.only.contents", FALSE),
37 add.to.row = getOption("xtable.add.to.row", NULL),
38 sanitize.text.function = getOption("xtable.sanitize.text.function", NULL),
39 sanitize.rownames.function = getOption("xtable.sanitize.rownames.function",
40 sanitize.text.function),
41 sanitize.colnames.function = getOption("xtable.sanitize.colnames.function",
42 sanitize.text.function),
43 math.style.negative = getOption("xtable.math.style.negative", FALSE),
44 math.style.exponents = getOption("xtable.math.style.exponents", FALSE),
45 html.table.attributes = getOption("xtable.html.table.attributes",
47 print.results = getOption("xtable.print.results", TRUE),
48 format.args = getOption("xtable.format.args", NULL),
49 rotate.rownames = getOption("xtable.rotate.rownames", FALSE),
50 rotate.colnames = getOption("xtable.rotate.colnames", FALSE),
51 booktabs = getOption("xtable.booktabs", FALSE),
52 scalebox = getOption("xtable.scalebox", NULL),
53 width = getOption("xtable.width", NULL),
54 comment = getOption("xtable.comment", TRUE),
55 timestamp = getOption("xtable.timestamp", date()),
60 \item{x}{For \code{xtableFtable}, an object of class
61 \code{"ftable"}. For \code{print.xtableFtable}, an object of class
62 \code{c("xtableFtable", "ftable")}.}
63 \item{caption}{Character vector of length 1 or 2 containing the
64 table's caption or title. If length is 2, the second item is the
65 "short caption" used when LaTeX generates a "List of Tables". Set to
66 \code{NULL} to suppress the caption. Default value is \code{NULL}. }
67 \item{label}{Character vector of length 1 containing the LaTeX label
68 or HTML anchor. Set to \code{NULL} to suppress the label. Default
69 value is \code{NULL}. }
70 \item{align}{Character vector of length equal to the number of columns
71 of the resulting table, indicating the alignment of the corresponding
72 columns. Also, \code{"|"} may be used to produce vertical lines
73 between columns in LaTeX tables, but these are effectively ignored
74 when considering the required length of the supplied vector. If a
75 character vector of length one is supplied, it is split as
76 \code{strsplit(align, "")[[1]]} before processing. For a flat table,
77 the number of columns is the number of columns of data, plus the
78 number of row variables in the table, plus one for the row names,
79 even though row names are not printed.
80 Use \code{"l"}, \code{"r"}, and \code{"c"} to
81 denote left, right, and center alignment, respectively. Use
82 \code{"p{3cm}"} etc. for a LaTeX column of the specified width. For
83 HTML output the \code{"p"} alignment is interpreted as \code{"l"},
84 ignoring the width request.
85 If \code{NULL} all row variable labels will be left aligned,
86 separated from the data columns by a vertical line, and all data
87 columns will be right aligned. The actual length of \code{align}
88 depends on the value of \code{method}.}
90 Numeric vector of length equal to one (in which case it will be
91 replicated as necessary) or to the number of columns in the
92 resulting table. Since data in the table consists of
93 counts, the default is 0. If the value of \code{digits} is negative, the
94 corresponding columns are displayed in scientific format
95 with \code{abs(digits)} digits.}
97 Character vector of length equal to the number of columns of the
98 resulting table, indicating the format for the corresponding columns.
99 These values are passed to the \code{formatC}
100 function. Use \code{"d"} (for integers), \code{"f"}, \code{"e"},
101 \code{"E"}, \code{"g"}, \code{"G"}, \code{"fg"} (for reals), or
102 \code{"s"} (for strings). \code{"f"} gives numbers in the usual
103 \code{xxx.xxx} format; \code{"e"} and \code{"E"} give
104 \code{n.ddde+nn} or \code{n.dddE+nn} (scientific format); \code{"g"}
105 and \code{"G"} put \code{x[i]} into scientific format only if it
106 saves space to do so. \code{"fg"} uses fixed format as \code{"f"},
107 but \code{digits} as number of \emph{significant} digits. Note that
108 this can lead to quite long result strings.
109 If \code{NULL} all row variable names and labels will have format
110 \code{"s"}, and all data columns will have format \code{"d"}. The
111 actual length of \code{display} depends on the value of
113 \item{quote}{a character string giving the set of quoting characters
114 for \code{format.ftable} used in \code{print.xtableFtable}; to
115 disable quoting altogether, use \code{quote=""}.}
117 \item{method}{string specifying how the \code{"xtableFtable"} object is
118 printed in the \code{print} method. Can be abbreviated. Available
119 methods are (see the examples in \code{\link{print.ftable}}):
121 \item{"non.compact"}{the default representation of an
122 \code{"ftable"} object.}
123 \item{"row.compact"}{a row-compact version without empty cells
124 below the column labels.}
125 \item{"col.compact"}{a column-compact version without empty cells
126 to the right of the row labels.}
127 \item{"compact"}{a row- and column-compact version. This may imply
128 a row and a column label sharing the same cell. They are then
129 separated by the string \code{lsep}.}
132 \item{lsep}{only for \code{method = "compact"}, the separation string
133 for row and column labels.}
134 \item{type}{Type of table to produce. Possible values for \code{type}
135 are \code{"latex"} or \code{"html"}.
136 Default value is \code{"latex"} and is the only type implemented so far.}
137 \item{file}{Name of file where the resulting code should be saved. If
138 \code{file=""}, output is displayed on screen. Note that the
139 function also (invisibly) returns a character vector of the results
140 (which can be helpful for post-processing).
141 Default value is \code{""}.}
142 \item{append}{If \code{TRUE} and \code{file!=""}, code will be
143 appended to \code{file} instead of overwriting \code{file}.
144 Default value is \code{FALSE}.}
145 \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting
146 table will be a floating table (using, for example,
147 \code{\\begin\{table\}} and \code{\\end\{table\}}). See
148 \code{floating.environment} below.
149 Default value is \code{TRUE}. }
150 \item{floating.environment}{If \code{floating=TRUE} and
151 \code{type="latex"}, the resulting table uses the specified floating
152 environment. Possible values include \code{"table"}, \code{"table*"},
153 and other floating environments defined in LaTeX packages.
154 Default value is \code{"table"}.}
155 \item{table.placement}{If \code{floating=TRUE} and
156 \code{type="latex"}, the floating table will have placement given by
157 \code{table.placement} where \code{table.placement} must be
158 \code{NULL} or contain only elements of
159 \{"h","t","b","p","!","H"\}.
160 Default value is \code{"ht"}.}
161 \item{caption.placement}{The caption will be placed at the bottom
162 of the table if \code{caption.placement} is \code{"bottom"} and at
163 the top of the table if it equals \code{"top"}.
164 Default value is \code{"bottom"}.}
165 \item{caption.width}{The caption will be placed in a \code{"parbox"}
166 of the specified width if \code{caption.width} is not \code{NULL} and
167 \code{type="latex"}. Default value is \code{NULL}.}
168 \item{latex.environments}{If \code{floating=TRUE} and
169 \code{type="latex"}, the specified LaTeX environments (provided as
170 a character vector) will enclose the tabular environment.
171 Default value is \code{"center"}. }
172 \item{tabular.environment}{When \code{type="latex"}, the tabular
173 environment that will be used.
174 When working with tables that extend more than one page, using
175 \code{tabular.environment="longtable"} with the corresponding
176 LaTeX package (see Fairbairns, 2005) allows one to typeset them
177 uniformly. Note that \code{floating} should be set to
178 \code{FALSE} when using the \code{longtable} environment.
179 Default value is \code{"tabular"}.}
180 \item{size}{A character vector that is inserted just before the
181 tabular environment starts. This can be used to set the font size
182 and a variety of other table settings. Initial backslashes are
183 automatically prefixed, if not supplied by user.
184 Default value is \code{NULL}. }
185 \item{hline.after}{When \code{type="latex"}, a vector of numbers
186 between -1 and \code{nrow(x)}, inclusive, indicating the rows after
187 which a horizontal line should appear. Repeated values are
188 allowed. If \code{NULL} the default is to draw a line before before
189 starting the table, after the column variable names and labels, and
190 at the end of the table.}
191 \item{NA.string}{String to be used for missing values in table
193 Default value is \code{""}.}
194 \item{only.contents}{If \code{TRUE} only the rows of the
196 Default value is \code{FALSE}. }
197 \item{add.to.row}{A list of two components. The first component (which
198 should be called 'pos') is a list that contains the position of rows on
199 which extra commands should be added at the end. The second
200 component (which should be called 'command') is a character vector
201 of the same length as the first component, which contains the command
202 that should be added at the end of the specified rows.
203 Default value is \code{NULL}, i.e. do not add commands.}
204 \item{sanitize.text.function}{All non-numeric entries (except row and
205 column names) are sanitized in an attempt to remove characters which
206 have special meaning for the output format. If
207 \code{sanitize.text.function} is not \code{NULL}, it should
208 be a function taking a character vector and returning one, and will
209 be used for the sanitization instead of the default internal
211 Default value is \code{NULL}.}
212 \item{sanitize.rownames.function}{Like the
213 \code{sanitize.text.function}, but applicable to row names.
214 The default uses the \code{sanitize.text.function}. }
215 \item{sanitize.colnames.function}{Like the
216 \code{sanitize.text.function}, but applicable to column names.
217 The default uses the \code{sanitize.text.function}. }
218 \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use
219 $-$ for the negative sign (as was the behavior prior to version 1.5-3).
220 Default value is \code{FALSE}.}
221 \item{math.style.exponents}{In a LaTeX table, if \code{TRUE} or
222 \code{"$$"}, then use \verb{$5 \times 10^{5}$} for 5e5. If
223 \code{"ensuremath"}, then use \verb{\\ensuremath{5 \times 10^{5}}}
224 for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to
225 approximate the LaTeX typsetting for 5e5.
226 Default value is \code{FALSE}.}
227 \item{html.table.attributes}{In an HTML table, attributes associated
228 with the \code{<TABLE>} tag.
229 Default value is \code{"border=1"}.}
230 \item{print.results}{If \code{TRUE}, the generated table is printed to
231 standard output. Set this to \code{FALSE} if you will just be using
232 the character vector that is returned invisibly.
233 Default value is \code{TRUE}.}
234 \item{format.args}{List of arguments for the \code{formatC} function.
235 For example, standard German number separators can be specified as
236 \code{format.args=list(big.mark = "'", decimal.mark =
237 ","))}. The arguments \code{digits} and \code{format} should not be
238 included in this list.
239 Default value is \code{NULL}.}
240 \item{rotate.rownames}{If \code{TRUE}, the row names and labels, and
241 column variable names are displayed vertically in LaTeX.
242 Default value is \code{FALSE}.}
243 \item{rotate.colnames}{If \code{TRUE}, the column names and labels,
244 and row variable names are displayed vertically in LaTeX.
245 Default value is \code{FALSE}.}
246 \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and
247 \code{bottomrule} commands from the LaTeX "booktabs" package are used
248 rather than \code{hline} for the horizontal line tags. }
249 \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be
250 added around the tabular environment with the specified value used
251 as the scaling factor.
252 Default value is \code{NULL}.}
253 \item{width}{If not \code{NULL}, the specified value is included in
254 parentheses between the tabular environment \code{begin} tag and the
255 alignment specification. This allows specification of the table
256 width when using tabular environments such as \code{tabular*} and
257 \code{tabularx}. Note that table width specification is not
258 supported with the \code{tabular} or \code{longtable} environments.
259 Default value is \code{NULL}.}
260 \item{comment}{If \code{TRUE}, the version and timestamp comment is
261 included. Default value is \code{TRUE}. }
262 \item{timestamp}{Timestamp to include in LaTeX comment. Set this
263 to \code{NULL} to exclude the timestamp. Default value is \code{date()}. }
264 \item{...}{Additional arguments. (Currently ignored.) }
267 \code{xtableFtable} carries out some calculations to determine the
268 number of rows and columns of names and labels which will be in the
269 table when formatted as a flat table, which depends on the value of
270 \code{method}. It uses the results of those calculations to set
271 sensible values for \code{align} and \code{display} if these have
272 not been supplied. It attaches attributes to the resulting object
273 which specify details of the function call which are needed when
274 printing the resulting object which is of class
275 \code{c("xtableFtable", "ftable")}.
277 \code{print.xtableFtable} uses the attributes attached to an object
278 of class \code{c("xtableFtable", "ftable")} to create a suitable
279 character matrix object for subsequent printing via a call to
280 \code{stats:::format.ftable}. This matrix object is then printed via
281 a call to \code{print.xtable}.
283 Note that at present there is no code for \code{type = "html"}.
286 For \code{xtableFtable} an object of class \code{c("xtableFtable",
287 "ftable")}, with attributes
288 \item{ftableCaption}{the value of the \code{caption} argument}
289 \item{ftableLabel}{the value of the \code{label} argument}
290 \item{ftableAlign}{the value of the \code{label} argument}
291 \item{ftableDigits}{the value of the \code{digits} argument or the
292 default value if \code{digits = NULL}}
293 \item{quote}{the value of the \code{quote} argument}
294 \item{ftableDisplay}{the value of the \code{display} argument or the
295 default value if \code{align = NULL}}
296 \item{method}{the value of the \code{method} argument}
297 \item{lsep}{the value of the \code{lsep} argument}
298 \item{nChars}{a vector of length 2 giving the number of character rows
299 and the number of character columns}
301 For \code{print.xtableFtable} a character string which will produce a
302 formatted table when included in a LaTeX document.
306 Fairbairns, Robin (2005) \emph{Tables longer than a single page.} The
307 UK List of TeX Frequently Asked Questions on the
308 Web. \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=longtab}
311 David Scott \email{d.scott@auckland.ac.nz}.
314 It is not recommended that users change the values of \code{align},
315 \code{digits} or \code{align}. First of all, alternative values have
316 not been tested. Secondly, it is most likely that to determine
317 appropriate values for these arguments, users will have to investigate
318 the code for \code{xtableFtable} and/or \code{print.xtableFtable}.
322 \code{\link{ftable}}, \code{\link{print.ftable}},
323 \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}},
324 \code{\link{align}}, \code{\link{digits}}, \code{\link{display}},
325 \code{\link{formatC}}
329 mtcars$cyl <- factor(mtcars$cyl, levels = c("4","6","8"),
330 labels = c("four","six","eight"))
331 tbl <- ftable(mtcars$cyl, mtcars$vs, mtcars$am, mtcars$gear,
333 dnn = c("Cylinders", "V/S", "Transmission", "Gears"))
334 xftbl <- xtableFtable(tbl, method = "compact")
335 print.xtableFtable(xftbl, booktabs = TRUE)
336 xftbl <- xtableFtable(tbl, method = "row.compact")
337 print.xtableFtable(xftbl, rotate.colnames = TRUE,
338 rotate.rownames = TRUE)