Skip to contents

Create and Export Lists of Tables

xtableList.Rd

xtableList creates an object from a list of tables, which can be used by print.xtableList to produce a composite table containing the information from the individual tables.

Usage

xtableList(x, caption = NULL, label = NULL,
           align = NULL, digits = NULL, display = NULL, ...)

# S3 method for class 'xtableList'
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 = NULL,
  NA.string = getOption("xtable.NA.string", ""),
  include.rownames = getOption("xtable.include.rownames", TRUE),
  include.colnames = getOption("xtable.include.colnames", TRUE),
  colnames.format = "single",
  only.contents = getOption("xtable.only.contents", FALSE),
  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),
  sanitize.subheadings.function =
    getOption("xtable.sanitize.subheadings.function",
              sanitize.text.function),
  sanitize.message.function =
    getOption("xtable.sanitize.message.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

For xtableList, a list of R objects all of the same class, being a class found among methods(xtable). The list may also have attributes "subheadings" and "message". The attribute "subheadings" should be a character vector of the same length as the list x. The attribute "message" should be a character vector of any length. For print.xtableList, an object of class xtableList produced by a call to xtableList.

caption

Character vector of length 1 or 2 containing the table's caption or title. If length is 2, the second item is the "short caption" used when LaTeX generates a "List of Tables". Set to NULL to suppress the caption. Default value is NULL.

label

Character vector of length 1 containing the LaTeX label or HTML anchor. Set to NULL to suppress the label. Default value is NULL.

align

Character vector of length equal to the number of columns of the resulting table, indicating the alignment of the corresponding columns. Also, "|" may be used to produce vertical lines between columns in LaTeX tables, but these are effectively ignored when considering the required length of the supplied vector. If a character vector of length one is supplied, it is split as strsplit(align, "")[[1]] before processing. Since the row names are printed in the first column, the length of align is one greater than ncol(x) if x is a data.frame. Use "l", "r", and "c" to denote left, right, and center alignment, respectively. Use "p{3cm}" etc. for a LaTeX column of the specified width. For HTML output the "p" alignment is interpreted as "l", ignoring the width request. Default depends on the class of x.

digits

Either NULL, or a vector of length one, or a vector of length equal to the number of columns in the resulting table, indicating the number of digits to display in the corresponding columns, or a list if length equal to the number of R objects making up x, all members being vectors of the same length, either length one or of length equal to the number of columns in the resulting table. See details for further information.

display

Either NULL, or a vector of length one, or a vector of length equal to the number of columns in the resulting table, indicating the format of the corresponding columns, or a list if length equal to the number of R objects making up x, all members being vectors of the same length, either length one or of length equal to the number of columns in the resulting table. See details for further information.

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 the number of rows in the resulting table, inclusive, indicating the rows after which a horizontal line should appear. Determining row numbers is not straightforward since some lines in the resulting table don't enter into the count. The default depends on the value of col.names.format.

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.

colnames.format

Either "single" or "multiple". Default is "single".

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.

sanitize.subheadings.function

Like the sanitize.text.function, but applicable to subheadings. The default uses the sanitize.text.function.

sanitize.message.function

Like the sanitize.text.function, but applicable to the message. 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

xtableList produces an object suitable for printing using print.xtableList.

The elements of the list x supplied to xtableList must all have the same structure. When these list items are submitted to xtable the resulting table must have the same number of columns with the same column names and type of data.

The values supplied to arguments digits and display, must be composed of elements as specified in those same arguments for the function xtable. See the help for xtable for details.

print.xtableList produces tables in two different formats depending on the value of col.names.format. If col.names.format = "single", the resulting table has only a single heading row. If col.names.format = "multiple" there is a heading row for each of the subtables making up the complete table.

By default if col.names.format = "single", there are horizontal lines above and below the heading row, and at the end of each subtable. If col.names.format = "multiple", there are horizontal lines above and below each appearance of the heading row, and at the end of each subtable.

If "subheadings" is not NULL, the individual elements of this vector (which can include newlines \n) produce a heading line or lines for the subtables. When col.names.format = "multiple" these subheadings appear above the heading rows.

If "message" is not NULL the vector produces a line or lines at the end of the table.

Consult the vignette ‘The xtableList Gallery’ to see the behaviour of these functions.

Note that at present there is no code for type = "html".

Value

xtableList produces an object of class "xtableList". An object of this class is a list of "xtable" objects with some additional attributes. Each element of the list can have a "subheading" attribute. The list can also have a "message" attribute.

print.xtableList produces a character string containing LaTeX markup which produces a composite table in a LaTeX document.

Author

David Scott d.scott@auckland.ac.nz.

See also

xtable, print.xtable, formatC

caption, label, align, digits, display

Examples

data(mtcars)
mtcars <- mtcars[, 1:6]
mtcarsList <- split(mtcars, f = mtcars$cyl)
attr(mtcarsList, "subheadings") <- paste0("Number of cylinders = ",
                                          names(mtcarsList))
attr(mtcarsList, "message") <- c("Line 1 of Message",
                                 "Line 2 of Message")
xList <- xtableList(mtcarsList)
print.xtableList(xList)
#> % latex table generated in R 4.5.1 by xtable 1.8-8 package
#> % Thu Mar  5 20:17:26 2026
#> \begin{table}[ht]
#> \centering
#> \begin{tabular}{rrrrrrr}
#>   \hline
#>  & mpg & cyl & disp & hp & drat & wt \\ 
#>   \hline
#> \multicolumn{7}{l}{Number of cylinders = 4}\\
#> Datsun 710 & 22.80 & 4.00 & 108.00 & 93.00 & 3.85 & 2.32 \\ 
#>   Merc 240D & 24.40 & 4.00 & 146.70 & 62.00 & 3.69 & 3.19 \\ 
#>   Merc 230 & 22.80 & 4.00 & 140.80 & 95.00 & 3.92 & 3.15 \\ 
#>   Fiat 128 & 32.40 & 4.00 & 78.70 & 66.00 & 4.08 & 2.20 \\ 
#>   Honda Civic & 30.40 & 4.00 & 75.70 & 52.00 & 4.93 & 1.61 \\ 
#>   Toyota Corolla & 33.90 & 4.00 & 71.10 & 65.00 & 4.22 & 1.83 \\ 
#>   Toyota Corona & 21.50 & 4.00 & 120.10 & 97.00 & 3.70 & 2.46 \\ 
#>   Fiat X1-9 & 27.30 & 4.00 & 79.00 & 66.00 & 4.08 & 1.94 \\ 
#>   Porsche 914-2 & 26.00 & 4.00 & 120.30 & 91.00 & 4.43 & 2.14 \\ 
#>   Lotus Europa & 30.40 & 4.00 & 95.10 & 113.00 & 3.77 & 1.51 \\ 
#>   Volvo 142E & 21.40 & 4.00 & 121.00 & 109.00 & 4.11 & 2.78 \\ 
#>    \hline
#> \multicolumn{7}{l}{Number of cylinders = 6}\\
#> Mazda RX4 & 21.00 & 6.00 & 160.00 & 110.00 & 3.90 & 2.62 \\ 
#>   Mazda RX4 Wag & 21.00 & 6.00 & 160.00 & 110.00 & 3.90 & 2.88 \\ 
#>   Hornet 4 Drive & 21.40 & 6.00 & 258.00 & 110.00 & 3.08 & 3.21 \\ 
#>   Valiant & 18.10 & 6.00 & 225.00 & 105.00 & 2.76 & 3.46 \\ 
#>   Merc 280 & 19.20 & 6.00 & 167.60 & 123.00 & 3.92 & 3.44 \\ 
#>   Merc 280C & 17.80 & 6.00 & 167.60 & 123.00 & 3.92 & 3.44 \\ 
#>   Ferrari Dino & 19.70 & 6.00 & 145.00 & 175.00 & 3.62 & 2.77 \\ 
#>    \hline
#> \multicolumn{7}{l}{Number of cylinders = 8}\\
#> Hornet Sportabout & 18.70 & 8.00 & 360.00 & 175.00 & 3.15 & 3.44 \\ 
#>   Duster 360 & 14.30 & 8.00 & 360.00 & 245.00 & 3.21 & 3.57 \\ 
#>   Merc 450SE & 16.40 & 8.00 & 275.80 & 180.00 & 3.07 & 4.07 \\ 
#>   Merc 450SL & 17.30 & 8.00 & 275.80 & 180.00 & 3.07 & 3.73 \\ 
#>   Merc 450SLC & 15.20 & 8.00 & 275.80 & 180.00 & 3.07 & 3.78 \\ 
#>   Cadillac Fleetwood & 10.40 & 8.00 & 472.00 & 205.00 & 2.93 & 5.25 \\ 
#>   Lincoln Continental & 10.40 & 8.00 & 460.00 & 215.00 & 3.00 & 5.42 \\ 
#>   Chrysler Imperial & 14.70 & 8.00 & 440.00 & 230.00 & 3.23 & 5.34 \\ 
#>   Dodge Challenger & 15.50 & 8.00 & 318.00 & 150.00 & 2.76 & 3.52 \\ 
#>   AMC Javelin & 15.20 & 8.00 & 304.00 & 150.00 & 3.15 & 3.44 \\ 
#>   Camaro Z28 & 13.30 & 8.00 & 350.00 & 245.00 & 3.73 & 3.84 \\ 
#>   Pontiac Firebird & 19.20 & 8.00 & 400.00 & 175.00 & 3.08 & 3.85 \\ 
#>   Ford Pantera L & 15.80 & 8.00 & 351.00 & 264.00 & 4.22 & 3.17 \\ 
#>   Maserati Bora & 15.00 & 8.00 & 301.00 & 335.00 & 3.54 & 3.57 \\ 
#>    \hline
#> \multicolumn{7}{l}{Line 1 of Message}\\
#> 
#> \multicolumn{7}{l}{Line 2 of Message}\\
#> \end{tabular}
#> \end{table}
print.xtableList(xList, colnames.format = "multiple")
#> % latex table generated in R 4.5.1 by xtable 1.8-8 package
#> % Thu Mar  5 20:17:26 2026
#> \begin{table}[ht]
#> \centering
#> \begin{tabular}{rrrrrrr}
#>    
#> \multicolumn{7}{l}{Number of cylinders = 4}\\ 
#> \hline
#>  & mpg & cyl & disp & hp & drat & wt \\\hline
#> 
#> Datsun 710 & 22.80 & 4.00 & 108.00 & 93.00 & 3.85 & 2.32 \\ 
#>   Merc 240D & 24.40 & 4.00 & 146.70 & 62.00 & 3.69 & 3.19 \\ 
#>   Merc 230 & 22.80 & 4.00 & 140.80 & 95.00 & 3.92 & 3.15 \\ 
#>   Fiat 128 & 32.40 & 4.00 & 78.70 & 66.00 & 4.08 & 2.20 \\ 
#>   Honda Civic & 30.40 & 4.00 & 75.70 & 52.00 & 4.93 & 1.61 \\ 
#>   Toyota Corolla & 33.90 & 4.00 & 71.10 & 65.00 & 4.22 & 1.83 \\ 
#>   Toyota Corona & 21.50 & 4.00 & 120.10 & 97.00 & 3.70 & 2.46 \\ 
#>   Fiat X1-9 & 27.30 & 4.00 & 79.00 & 66.00 & 4.08 & 1.94 \\ 
#>   Porsche 914-2 & 26.00 & 4.00 & 120.30 & 91.00 & 4.43 & 2.14 \\ 
#>   Lotus Europa & 30.40 & 4.00 & 95.10 & 113.00 & 3.77 & 1.51 \\ 
#>   Volvo 142E & 21.40 & 4.00 & 121.00 & 109.00 & 4.11 & 2.78 \\ 
#>    \hline\\ 
#> \multicolumn{7}{l}{Number of cylinders = 6}\\ 
#> \hline
#>  & mpg & cyl & disp & hp & drat & wt \\\hline
#> Mazda RX4 & 21.00 & 6.00 & 160.00 & 110.00 & 3.90 & 2.62 \\ 
#>   Mazda RX4 Wag & 21.00 & 6.00 & 160.00 & 110.00 & 3.90 & 2.88 \\ 
#>   Hornet 4 Drive & 21.40 & 6.00 & 258.00 & 110.00 & 3.08 & 3.21 \\ 
#>   Valiant & 18.10 & 6.00 & 225.00 & 105.00 & 2.76 & 3.46 \\ 
#>   Merc 280 & 19.20 & 6.00 & 167.60 & 123.00 & 3.92 & 3.44 \\ 
#>   Merc 280C & 17.80 & 6.00 & 167.60 & 123.00 & 3.92 & 3.44 \\ 
#>   Ferrari Dino & 19.70 & 6.00 & 145.00 & 175.00 & 3.62 & 2.77 \\ 
#>    \hline\\ 
#> \multicolumn{7}{l}{Number of cylinders = 8}\\ 
#> \hline
#>  & mpg & cyl & disp & hp & drat & wt \\\hline
#> Hornet Sportabout & 18.70 & 8.00 & 360.00 & 175.00 & 3.15 & 3.44 \\ 
#>   Duster 360 & 14.30 & 8.00 & 360.00 & 245.00 & 3.21 & 3.57 \\ 
#>   Merc 450SE & 16.40 & 8.00 & 275.80 & 180.00 & 3.07 & 4.07 \\ 
#>   Merc 450SL & 17.30 & 8.00 & 275.80 & 180.00 & 3.07 & 3.73 \\ 
#>   Merc 450SLC & 15.20 & 8.00 & 275.80 & 180.00 & 3.07 & 3.78 \\ 
#>   Cadillac Fleetwood & 10.40 & 8.00 & 472.00 & 205.00 & 2.93 & 5.25 \\ 
#>   Lincoln Continental & 10.40 & 8.00 & 460.00 & 215.00 & 3.00 & 5.42 \\ 
#>   Chrysler Imperial & 14.70 & 8.00 & 440.00 & 230.00 & 3.23 & 5.34 \\ 
#>   Dodge Challenger & 15.50 & 8.00 & 318.00 & 150.00 & 2.76 & 3.52 \\ 
#>   AMC Javelin & 15.20 & 8.00 & 304.00 & 150.00 & 3.15 & 3.44 \\ 
#>   Camaro Z28 & 13.30 & 8.00 & 350.00 & 245.00 & 3.73 & 3.84 \\ 
#>   Pontiac Firebird & 19.20 & 8.00 & 400.00 & 175.00 & 3.08 & 3.85 \\ 
#>   Ford Pantera L & 15.80 & 8.00 & 351.00 & 264.00 & 4.22 & 3.17 \\ 
#>   Maserati Bora & 15.00 & 8.00 & 301.00 & 335.00 & 3.54 & 3.57 \\ 
#>    \hline
#> \multicolumn{7}{l}{Line 1 of Message}\\
#> 
#> \multicolumn{7}{l}{Line 2 of Message}\\
#> \end{tabular}
#> \end{table}