xtable: print.xtable – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

print.xtable

Print Export Tables

Description

Function returning and displaying or writing to disk the LaTeX or HTML code associated with the supplied object of class xtable.

Usage

## S3 method for class 'xtable'
print(x,
  type = getOption("xtable.type", "latex"),
  file = getOption("xtable.file", ""),
  append = getOption("xtable.append", FALSE),
  floating = getOption("xtable.floating", TRUE),
  floating.environment = getOption("xtable.floating.environment", "table"),
  table.placement = getOption("xtable.table.placement", "ht"),
  caption.placement = getOption("xtable.caption.placement", "bottom"),
  caption.width = getOption("xtable.caption.width", NULL),
  latex.environments = getOption("xtable.latex.environments", c("center")),
  tabular.environment = getOption("xtable.tabular.environment", "tabular"),
  size = getOption("xtable.size", NULL),
  hline.after = getOption("xtable.hline.after", c(-1,0,nrow(x))),
  NA.string = getOption("xtable.NA.string", ""),
  include.rownames = getOption("xtable.include.rownames", TRUE),
  include.colnames = getOption("xtable.include.colnames", TRUE),
  only.contents = getOption("xtable.only.contents", FALSE),
  add.to.row = getOption("xtable.add.to.row", NULL),
  sanitize.text.function = getOption("xtable.sanitize.text.function", NULL),
  sanitize.rownames.function = getOption("xtable.sanitize.rownames.function",
                                         sanitize.text.function),
  sanitize.colnames.function = getOption("xtable.sanitize.colnames.function",
                                         sanitize.text.function),
  math.style.negative = getOption("xtable.math.style.negative", FALSE),
  math.style.exponents = getOption("xtable.math.style.exponents", FALSE),
  html.table.attributes = getOption("xtable.html.table.attributes",
                                    "border=1"),
  print.results = getOption("xtable.print.results", TRUE),
  format.args = getOption("xtable.format.args", NULL),
  rotate.rownames = getOption("xtable.rotate.rownames", FALSE),
  rotate.colnames = getOption("xtable.rotate.colnames", FALSE),
  booktabs = getOption("xtable.booktabs", FALSE),
  scalebox = getOption("xtable.scalebox", NULL),
  width = getOption("xtable.width", NULL),
  comment = getOption("xtable.comment", TRUE),
  timestamp = getOption("xtable.timestamp", date()),
  ...)

Arguments

`x`	An object of class `"xtable"`.
`type`	Type of table to produce. Possible values for `type` are `"latex"` or `"html"`. Default value is `"latex"`.
`file`	Name of file where the resulting code should be saved. If `file=""`, output is displayed on screen. Note that the function also (invisibly) returns a character vector of the results (which can be helpful for post-processing). Default value is `""`.
`append`	If `TRUE` and `file!=""`, code will be appended to `file` instead of overwriting `file`. Default value is `FALSE`.
`floating`	If `TRUE` and `type="latex"`, the resulting table will be a floating table (using, for example, `\begin{table}` and `\end{table}`). See `floating.environment` below. Default value is `TRUE`.
`floating.environment`	If `floating=TRUE` and `type="latex"`, the resulting table uses the specified floating environment. Possible values include `"table"`, `"table*"`, and other floating environments defined in LaTeX packages. Default value is `"table"`.
`table.placement`	If `floating=TRUE` and `type="latex"`, the floating table will have placement given by `table.placement` where `table.placement` must be `NULL` or contain only elements of {"h","t","b","p","!","H"}. Default value is `"ht"`.
`caption.placement`	The caption will be placed at the bottom of the table if `caption.placement` is `"bottom"` and at the top of the table if it equals `"top"`. Default value is `"bottom"`.
`caption.width`	The caption will be placed in a `"parbox"` of the specified width if `caption.width` is not `NULL` and `type="latex"`. Default value is `NULL`.
`latex.environments`	If `floating=TRUE` and `type="latex"`, the specified LaTeX environments (provided as a character vector) will enclose the tabular environment. Default value is `"center"`.
`tabular.environment`	When `type="latex"`, the tabular environment that will be used. When working with tables that extend more than one page, using `tabular.environment="longtable"` with the corresponding LaTeX package (see Fairbairns, 2005) allows one to typeset them uniformly. Note that `floating` should be set to `FALSE` when using the `longtable` environment. Default value is `"tabular"`.
`size`	A character vector that is inserted just before the tabular environment starts. This can be used to set the font size and a variety of other table settings. Initial backslashes are automatically prefixed, if not supplied by user. Default value is `NULL`.
`hline.after`	When `type="latex"`, a vector of numbers between -1 and `nrow(x)`, inclusive, indicating the rows after which a horizontal line should appear. If `NULL` is used no lines are produced. Repeated values are allowed. Default value is `c(-1,0,nrow(x))` which means draw a line before and after the columns names and at the end of the table.
`NA.string`	String to be used for missing values in table entries. Default value is `""`.
`include.rownames`	If `TRUE` the rows names are printed. Default value is `TRUE`.
`include.colnames`	If `TRUE` the columns names are printed. Default value is `TRUE`.
`only.contents`	If `TRUE` only the rows of the table are printed. Default value is `FALSE`.
`add.to.row`	A list of two components. The first component (which should be called 'pos') is a list that contains the position of rows on which extra commands should be added at the end. The second component (which should be called 'command') is a character vector of the same length as the first component, which contains the command that should be added at the end of the specified rows. Default value is `NULL`, i.e. do not add commands.
`sanitize.text.function`	All non-numeric entries (except row and column names) are sanitized in an attempt to remove characters which have special meaning for the output format. If `sanitize.text.function` is not `NULL`, it should be a function taking a character vector and returning one, and will be used for the sanitization instead of the default internal function. Default value is `NULL`.
`sanitize.rownames.function`	Like the `sanitize.text.function`, but applicable to row names. The default uses the `sanitize.text.function`.
`sanitize.colnames.function`	Like the `sanitize.text.function`, but applicable to column names. The default uses the `sanitize.text.function`.
`math.style.negative`	In a LaTeX table, if `TRUE`, then use $-$ for the negative sign (as was the behavior prior to version 1.5-3). Default value is `FALSE`.
`math.style.exponents`	In a LaTeX table, if `TRUE` or `"$$"`, then use $5 \times 10^{5}$ for 5e5. If `"ensuremath"`, then use `\ensuremath{5 \times 10^{5}}` for 5e5. If `"UTF-8"` or `"UTF-8"`, then use UTF-8 to approximate the LaTeX typsetting for 5e5. Default value is `FALSE`.
`html.table.attributes`	In an HTML table, attributes associated with the `<TABLE>` tag. Default value is `"border=1"`.
`print.results`	If `TRUE`, the generated table is printed to standard output. Set this to `FALSE` if you will just be using the character vector that is returned invisibly. Default value is `TRUE`.
`format.args`	List of arguments for the `formatC` function. For example, standard German number separators can be specified as `format.args=list(big.mark = "'", decimal.mark = ","))`. The arguments `digits` and `format` should not be included in this list. See details. Default value is `NULL`.
`rotate.rownames`	If `TRUE`, the row names are displayed vertically in LaTeX. Default value is `FALSE`.
`rotate.colnames`	If `TRUE`, the column names are displayed vertically in LaTeX. Default value is `FALSE`.
`booktabs`	If `TRUE`, the `toprule`, `midrule` and `bottomrule` commands from the LaTeX "booktabs" package are used rather than `hline` for the horizontal line tags.
`scalebox`	If not `NULL`, a `scalebox` clause will be added around the tabular environment with the specified value used as the scaling factor. Default value is `NULL`.
`width`	If not `NULL`, the specified value is included in parentheses between the tabular environment `begin` tag and the alignment specification. This allows specification of the table width when using tabular environments such as `tabular*` and `tabularx`. Note that table width specification is not supported with the `tabular` or `longtable` environments. Default value is `NULL`.
`comment`	If `TRUE`, the version and timestamp comment is included. Default value is `TRUE`.
`timestamp`	Timestamp to include in LaTeX comment. Set this to `NULL` to exclude the timestamp. Default value is `date()`.
`...`	Additional arguments. (Currently ignored.)

Details

This function displays or writes to disk the code to produce a table associated with an object x of class "xtable". The resulting code is either a LaTeX or HTML table, depending on the value of type. The function also (invisibly) returns a character vector of the results (which can be helpful for post-processing).

Since version 1.4 the non default behavior of hline.after is changed. To obtain the same results as the previous versions add to the hline.after vector the vector c(-1, 0, nrow(x)) where nrow(x) is the numbers of rows of the object.

From version 1.4-3, all non-numeric columns are sanitized, and all LaTeX special characters are sanitized for LaTeX output. See Section 3 of the xtableGallery vignette for an example of customizing the sanitization. From version 1.4-4, the sanitization also applies to column names. To remove any text sanitization, specify sanitize.text.function=function(x){x}.

From version 1.6-1 the default values for the arguments other than x are obtained using getOption(). Hence the user can set the values once with options() rather than setting them in every call to print.xtable().

The argument format.args is used to supply arguments to the formatC function, but will throw an error if values for digits or format are included in the list of arguments. The recommended approach to specify digits is to supply the argument digits to xtable, and to specify format supply the argument display to xtable. See the examples.

Author(s)

David Dahl dahl@stat.byu.edu with contributions and suggestions from many others (see source code).

References

Fairbairns, Robin (2005) Tables longer than a single page. The UK List of TeX Frequently Asked Questions on the Web. http://www.tex.ac.uk/cgi-bin/texfaq2html?label=longtab

Examples

df <- data.frame(A = c(1.00123, 33.1, 6),
                 B = c(111111, 3333333, 3123.233))
## The following code gives the error
## formal argument "digits" matched by multiple actual arguments
## print(xtable(df, display = c("s","e","e")),
##       format.args = list(digits = 3, big.mark = " ", decimal.mark = ","))
## specify digits as argument to xtable instead
print(xtable(df, display = c("s","f","f"), digits = 4),
      format.args = list(big.mark = " ", decimal.mark = ","))
## The following code gives the error
## formal argument "format" matched by multiple actual arguments
## print(xtable(df, digits = 4),
##       format.args = list(format = c("s","e","e"),
##                          big.mark = " ", decimal.mark = ","))
## specify format using display argument in xtable
print(xtable(df, display = c("s","e","e"), digits = 4),
      format.args = list(big.mark = " ", decimal.mark = ","))

xtable

Export Tables to LaTeX or HTML

v1.8-4

GPL (>= 2)

Authors

David B. Dahl [aut], David Scott [aut, cre], Charles Roosen [aut], Arni Magnusson [aut], Jonathan Swinton [aut], Ajay Shah [ctb], Arne Henningsen [ctb], Benno Puetz [ctb], Bernhard Pfaff [ctb], Claudio Agostinelli [ctb], Claudius Loehnert [ctb], David Mitchell [ctb], David Whiting [ctb], Fernando da Rosa [ctb], Guido Gay [ctb], Guido Schulz [ctb], Ian Fellows [ctb], Jeff Laake [ctb], John Walker [ctb], Jun Yan [ctb], Liviu Andronic [ctb], Markus Loecher [ctb], Martin Gubri [ctb], Matthieu Stigler [ctb], Robert Castelo [ctb], Seth Falcon [ctb], Stefan Edwards [ctb], Sven Garbade [ctb], Uwe Ligges [ctb]

Initial release

2019-04-08