3 \title{Print Export Tables}
\r
5 Function returning and displaying or writing to disk the LaTeX or HTML
\r
6 code associated with the supplied object of class \code{xtable}.
\r
9 \method{print}{xtable}(x,
\r
10 type = getOption("xtable.type", "latex"),
\r
11 file = getOption("xtable.file", ""),
\r
12 append = getOption("xtable.append", FALSE),
\r
13 floating = getOption("xtable.floating", TRUE),
\r
14 floating.environment = getOption("xtable.floating.environment", "table"),
\r
15 table.placement = getOption("xtable.table.placement", "ht"),
\r
16 caption.placement = getOption("xtable.caption.placement", "bottom"),
\r
17 caption.width = getOption("xtable.caption.width", NULL),
\r
18 latex.environments = getOption("xtable.latex.environments", c("center")),
\r
19 tabular.environment = getOption("xtable.tabular.environment", "tabular"),
\r
20 size = getOption("xtable.size", NULL),
\r
21 hline.after = getOption("xtable.hline.after", c(-1,0,nrow(x))),
\r
22 NA.string = getOption("xtable.NA.string", ""),
\r
23 include.rownames = getOption("xtable.include.rownames", TRUE),
\r
24 include.colnames = getOption("xtable.include.colnames", TRUE),
\r
25 only.contents = getOption("xtable.only.contents", FALSE),
\r
26 add.to.row = getOption("xtable.add.to.row", NULL),
\r
27 sanitize.text.function = getOption("xtable.sanitize.text.function", NULL),
\r
28 sanitize.rownames.function = getOption("xtable.sanitize.rownames.function",
\r
29 sanitize.text.function),
\r
30 sanitize.colnames.function = getOption("xtable.sanitize.colnames.function",
\r
31 sanitize.text.function),
\r
32 math.style.negative = getOption("xtable.math.style.negative", FALSE),
\r
33 math.style.exponents = getOption("xtable.math.style.exponents", FALSE),
\r
34 html.table.attributes = getOption("xtable.html.table.attributes",
\r
36 print.results = getOption("xtable.print.results", TRUE),
\r
37 format.args = getOption("xtable.format.args", NULL),
\r
38 rotate.rownames = getOption("xtable.rotate.rownames", FALSE),
\r
39 rotate.colnames = getOption("xtable.rotate.colnames", FALSE),
\r
40 booktabs = getOption("xtable.booktabs", FALSE),
\r
41 scalebox = getOption("xtable.scalebox", NULL),
\r
42 width = getOption("xtable.width", NULL),
\r
43 comment = getOption("xtable.comment", TRUE),
\r
44 timestamp = getOption("xtable.timestamp", date()),
\r
47 \item{x}{An object of class \code{"xtable"}.}
\r
48 \item{type}{Type of table to produce. Possible values for \code{type}
\r
49 are \code{"latex"} or \code{"html"}.
\r
50 Default value is \code{"latex"}.}
\r
51 \item{file}{Name of file where the resulting code should be saved. If
\r
52 \code{file=""}, output is displayed on screen. Note that the
\r
53 function also (invisibly) returns a character vector of the results
\r
54 (which can be helpful for post-processing).
\r
55 Default value is \code{""}.}
\r
56 \item{append}{If \code{TRUE} and \code{file!=""}, code will be
\r
57 appended to \code{file} instead of overwriting \code{file}.
\r
58 Default value is \code{FALSE}.}
\r
59 \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting
\r
60 table will be a floating table (using, for example,
\r
61 \code{\\begin\{table\}} and \code{\\end\{table\}}). See
\r
62 \code{floating.environment} below.
\r
63 Default value is \code{TRUE}. }
\r
64 \item{floating.environment}{If \code{floating=TRUE} and
\r
65 \code{type="latex"}, the resulting table uses the specified floating
\r
66 environment. Possible values include \code{"table"}, \code{"table*"},
\r
67 and other floating environments defined in LaTeX packages.
\r
68 Default value is \code{"table"}.}
\r
69 \item{table.placement}{If \code{floating=TRUE} and
\r
70 \code{type="latex"}, the floating table will have placement given by
\r
71 \code{table.placement} where \code{table.placement} must be
\r
72 \code{NULL} or contain only elements of
\r
73 \{"h","t","b","p","!","H"\}.
\r
74 Default value is \code{"ht"}.}
\r
75 \item{caption.placement}{The caption will be placed at the bottom
\r
76 of the table if \code{caption.placement} is \code{"bottom"} and at
\r
77 the top of the table if it equals \code{"top"}.
\r
78 Default value is \code{"bottom"}.}
\r
79 \item{caption.width}{The caption will be placed in a \code{"parbox"}
\r
80 of the specified width if \code{caption.width} is not \code{NULL} and
\r
81 \code{type="latex"}. Default value is \code{NULL}.}
\r
82 \item{latex.environments}{If \code{floating=TRUE} and
\r
83 \code{type="latex"}, the specified LaTeX environments (provided as
\r
84 a character vector) will enclose the tabular environment.
\r
85 Default value is \code{"center"}. }
\r
86 \item{tabular.environment}{When \code{type="latex"}, the tabular
\r
87 environment that will be used.
\r
88 When working with tables that extend more than one page, using
\r
89 \code{tabular.environment="longtable"} with the corresponding
\r
90 LaTeX package (see Fairbairns, 2005) allows one to typeset them
\r
91 uniformly. Note that \code{floating} should be set to
\r
92 \code{FALSE} when using the \code{longtable} environment.
\r
93 Default value is \code{"tabular"}.}
\r
94 \item{size}{A character vector that is inserted just before the
\r
95 tabular environment starts. This can be used to set the font size
\r
96 and a variety of other table settings. Initial backslashes are
\r
97 automatically prefixed, if not supplied by user.
\r
98 Default value is \code{NULL}. }
\r
99 \item{hline.after}{When \code{type="latex"}, a vector of numbers
\r
100 between -1 and \code{nrow(x)}, inclusive, indicating the rows
\r
101 after which a horizontal line should appear. If \code{NULL} is used
\r
102 no lines are produced. Repeated values are allowed.
\r
103 Default value is \code{c(-1,0,nrow(x))} which means draw a line
\r
104 before and after the columns names and at the end of the
\r
106 \item{NA.string}{String to be used for missing values in table
\r
108 Default value is \code{""}.}
\r
109 \item{include.rownames}{If \code{TRUE} the rows names are
\r
111 Default value is \code{TRUE}.}
\r
112 \item{include.colnames}{If \code{TRUE} the columns names are
\r
114 Default value is \code{TRUE}.}
\r
115 \item{only.contents}{If \code{TRUE} only the rows of the
\r
117 Default value is \code{FALSE}. }
\r
118 \item{add.to.row}{A list of two components. The first component (which
\r
119 should be called 'pos') is a list that contains the position of rows on
\r
120 which extra commands should be added at the end. The second
\r
121 component (which should be called 'command') is a character vector
\r
122 of the same length as the first component, which contains the command
\r
123 that should be added at the end of the specified rows.
\r
124 Default value is \code{NULL}, i.e. do not add commands.}
\r
125 \item{sanitize.text.function}{All non-numeric entries (except row and
\r
126 column names) are sanitized in an attempt to remove characters which
\r
127 have special meaning for the output format. If
\r
128 \code{sanitize.text.function} is not \code{NULL}, it should
\r
129 be a function taking a character vector and returning one, and will
\r
130 be used for the sanitization instead of the default internal
\r
132 Default value is \code{NULL}.}
\r
133 \item{sanitize.rownames.function}{Like the
\r
134 \code{sanitize.text.function}, but applicable to row names.
\r
135 The default uses the \code{sanitize.text.function}. }
\r
136 \item{sanitize.colnames.function}{Like the
\r
137 \code{sanitize.text.function}, but applicable to column names.
\r
138 The default uses the \code{sanitize.text.function}. }
\r
139 \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use
\r
140 $-$ for the negative sign (as was the behavior prior to version 1.5-3).
\r
141 Default value is \code{FALSE}.}
\r
142 \item{math.style.exponents}{In a LaTeX table, if \code{TRUE} or
\r
143 \code{"$$"}, then use \verb{$5 \times 10^{5}$} for 5e5. If
\r
144 \code{"ensuremath"}, then use \verb{\\ensuremath{5 \times 10^{5}}}
\r
145 for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to
\r
146 approximate the LaTeX typsetting for 5e5.
\r
147 Default value is \code{FALSE}.}
\r
148 \item{html.table.attributes}{In an HTML table, attributes associated
\r
149 with the \code{<TABLE>} tag.
\r
150 Default value is \code{"border=1"}.}
\r
151 \item{print.results}{If \code{TRUE}, the generated table is printed to
\r
152 standard output. Set this to \code{FALSE} if you will just be using
\r
153 the character vector that is returned invisibly.
\r
154 Default value is \code{TRUE}.}
\r
155 \item{format.args}{List of arguments for the \code{formatC} function.
\r
156 For example, standard German number separators can be specified as
\r
157 \code{format.args=list(big.mark = "'", decimal.mark =
\r
158 ","))}. The arguments \code{digits} and \code{format} should not be
\r
159 included in this list. See details.
\r
160 Default value is \code{NULL}.}
\r
161 \item{rotate.rownames}{If \code{TRUE}, the row names are displayed
\r
162 vertically in LaTeX.
\r
163 Default value is \code{FALSE}.}
\r
164 \item{rotate.colnames}{If \code{TRUE}, the column names are displayed
\r
165 vertically in LaTeX.
\r
166 Default value is \code{FALSE}.}
\r
167 \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and
\r
168 \code{bottomrule} commands from the LaTeX "booktabs" package are used
\r
169 rather than \code{hline} for the horizontal line tags. }
\r
170 \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be
\r
171 added around the tabular environment with the specified value used
\r
172 as the scaling factor.
\r
173 Default value is \code{NULL}.}
\r
174 \item{width}{If not \code{NULL}, the specified value is included in
\r
175 parentheses between the tabular environment \code{begin} tag and the
\r
176 alignment specification. This allows specification of the table
\r
177 width when using tabular environments such as \code{tabular*} and
\r
178 \code{tabularx}. Note that table width specification is not
\r
179 supported with the \code{tabular} or \code{longtable} environments.
\r
180 Default value is \code{NULL}.}
\r
181 \item{comment}{If \code{TRUE}, the version and timestamp comment is
\r
182 included. Default value is \code{TRUE}. }
\r
183 \item{timestamp}{Timestamp to include in LaTeX comment. Set this
\r
184 to \code{NULL} to exclude the timestamp. Default value is \code{date()}. }
\r
185 \item{...}{Additional arguments. (Currently ignored.) }
\r
188 This function displays or writes to disk the code to produce a table
\r
189 associated with an object \code{x} of class \code{"xtable"}.
\r
190 The resulting code is either a LaTeX or HTML table, depending on the
\r
191 value of \code{type}. The function also (invisibly) returns a
\r
192 character vector of the results (which can be helpful for
\r
195 Since version 1.4 the non default behavior of \code{hline.after} is
\r
196 changed. To obtain the same results as the previous versions add to
\r
197 the \code{hline.after} vector the vector \code{c(-1, 0, nrow(x))}
\r
198 where \code{nrow(x)} is the numbers of rows of the object.
\r
200 From version 1.4-3, all non-numeric columns are sanitized, and all
\r
201 LaTeX special characters are sanitized for LaTeX output. See Section
\r
202 3 of the \code{xtableGallery} vignette for an example of customizing
\r
203 the sanitization. From version 1.4-4, the sanitization also applies to
\r
204 column names. To remove any text sanitization, specify
\r
205 \code{sanitize.text.function=function(x){x}}.
\r
207 From version 1.6-1 the default values for the arguments other than
\r
208 \code{x} are obtained using \code{getOption()}. Hence the user can
\r
209 set the values once with \code{options()} rather than setting them in
\r
210 every call to \code{print.xtable()}.
\r
212 The argument \code{format.args} is used to supply arguments to the
\r
213 \code{formatC} function, but will throw an error if values for
\r
214 \code{digits} or \code{format} are included in the list of
\r
215 arguments. The recommended approach to specify \code{digits} is to supply
\r
216 the argument \code{digits} to \code{xtable}, and to specify
\r
217 \code{format} supply the argument \code{display} to \code{xtable}. See
\r
221 David Dahl \email{dahl@stat.byu.edu} with contributions and
\r
222 suggestions from many others (see source code).
\r
225 Fairbairns, Robin (2005) \emph{Tables longer than a single page.} The
\r
226 UK List of TeX Frequently Asked Questions on the
\r
227 Web. \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=longtab}
\r
230 \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}},
\r
231 \code{\link{align}}, \code{\link{digits}}, \code{\link{display}},
\r
232 \code{\link{formatC}}
\r
236 df <- data.frame(A = c(1.00123, 33.1, 6),
\r
237 B = c(111111, 3333333, 3123.233))
\r
238 ## The following code gives the error
\r
239 ## formal argument "digits" matched by multiple actual arguments
\r
240 ## print(xtable(df, display = c("s","e","e")),
\r
241 ## format.args = list(digits = 3, big.mark = " ", decimal.mark = ","))
\r
242 ## specify digits as argument to xtable instead
\r
243 print(xtable(df, display = c("s","f","f"), digits = 4),
\r
244 format.args = list(big.mark = " ", decimal.mark = ","))
\r
245 ## The following code gives the error
\r
246 ## formal argument "format" matched by multiple actual arguments
\r
247 ## print(xtable(df, digits = 4),
\r
248 ## format.args = list(format = c("s","e","e"),
\r
249 ## big.mark = " ", decimal.mark = ","))
\r
250 ## specify format using display argument in xtable
\r
251 print(xtable(df, display = c("s","e","e"), digits = 4),
\r
252 format.args = list(big.mark = " ", decimal.mark = ","))
\r
projects / xtable.git / blob