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