xtableFtable {xtable}

Create and Export Flat Tables

Description

xtableFtable creates an object which contains information about a flat table which can be used by print.xtableFtable to produce a character string which when included in a document produces a nicely formatted flat table.

Usage

xtableFtable(x, caption = NULL, label = NULL,
             align = NULL, digits = 0, display = NULL,
             quote = FALSE,
             method = c("non.compact", "row.compact",
                         "col.compact", "compact"),
             lsep = " $\\vert$ ", ...)

## S3 method for class 'xtableFtable'
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", NULL),
  NA.string = getOption("xtable.NA.string", ""),
  only.contents = getOption("xtable.only.contents", FALSE),
  add.to.row = getOption("xtable.add.to.row", NULL),
  sanitize.text.function = getOption("xtable.sanitize.text.function", as.is),
  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

For xtableFtable, an object of class "ftable". For print.xtableFtable, an object of class c("xtableFtable", "ftable").

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. For a flat table, the number of columns is the number of columns of data, plus the number of row variables in the table, plus one for the row names, even though row names are not printed. 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. If NULL all row variable labels will be left aligned, separated from the data columns by a vertical line, and all data columns will be right aligned. The actual length of align depends on the value of method.

digits

Numeric vector of length equal to one (in which case it will be replicated as necessary) or to the number of columns in the resulting table. Since data in the table consists of counts, the default is 0. If the value of digits is negative, the corresponding columns are displayed in scientific format with abs(digits) digits.

display

Character vector of length equal to the number of columns of the resulting table, indicating the format for the corresponding columns. These values are passed to the formatC function. Use "d" (for integers), "f", "e", "E", "g", "G", "fg" (for reals), or "s" (for strings). "f" gives numbers in the usual xxx.xxx format; "e" and "E" give n.ddde+nn or n.dddE+nn (scientific format); "g" and "G" put x[i] into scientific format only if it saves space to do so. "fg" uses fixed format as "f", but digits as number of significant digits. Note that this can lead to quite long result strings. If NULL all row variable names and labels will have format "s", and all data columns will have format "d". The actual length of display depends on the value of method.

quote

A character string giving the set of quoting characters for format.ftable used in print.xtableFtable. To disable quoting altogether, use quote="".

method

String specifying how the "xtableFtable" object is printed in the print method. Can be abbreviated. Available methods are (see the examples in print.ftable):

"non.compact"

the default representation of an "ftable" object.

"row.compact"

a row-compact version without empty cells below the column labels.

"col.compact"

a column-compact version without empty cells to the right of the row labels.

"compact"

a row- and column-compact version. This may imply a row and a column label sharing the same cell. They are then separated by the string lsep.

lsep

Only for method = "compact", the separation string for row and column labels.

type

Type of table to produce. Possible values for type are "latex" or "html". Default value is "latex" and is the only type implemented so far.

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. Repeated values are allowed. If NULL the default is to draw a line before before starting the table, after the column variable names and labels, and at the end of the table.

NA.string

String to be used for missing values in table entries. Default value is "".

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

Since the table entries are counts no sanitization is necessary. The default is as.is, which is the function which makes no changes. This also applies to the labels for the row and column variables since these are also part of the table which is printed using a call to print.xtable.

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 typesetting 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. Default value is NULL.

rotate.rownames

If TRUE, the row names and labels, and column variable names are displayed vertically in LaTeX. Default value is FALSE.

rotate.colnames

If TRUE, the column names and labels, and row variable 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

xtableFtable carries out some calculations to determine the number of rows and columns of names and labels which will be in the table when formatted as a flat table, which depends on the value of method. It uses the results of those calculations to set sensible values for align and display if these have not been supplied. It attaches attributes to the resulting object which specify details of the function call which are needed when printing the resulting object which is of class c("xtableFtable", "ftable").

print.xtableFtable uses the attributes attached to an object of class c("xtableFtable", "ftable") to create a suitable character matrix object for subsequent printing. Formatting is carried out by changing the class of the c("xtableFtable", "ftable") to "ftable" then using the generic format to invoke format.ftable, from the stats package. The matrix object produced is then printed via a call to print.xtable.

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

Value

For xtableFtable an object of class c("xtableFtable", "ftable"), with attributes

ftableCaption

the value of the caption argument

ftableLabel

the value of the label argument

ftableAlign

the value of the label argument

ftableDigits

the value of the digits argument or the default value if digits = NULL

quote

the value of the quote argument

ftableDisplay

the value of the display argument or the default value if align = NULL

method

the value of the method argument

lsep

the value of the lsep argument

nChars

a vector of length 2 giving the number of character rows and the number of character columns

For print.xtableFtable a character string which will produce a formatted table when included in a LaTeX document.

Note

The functions xtableFtable and print.xtableFtable are new and their behaviour may change in the future based on user experience and recommendations.

It is not recommended that users change the values of align, digits or align. First of all, alternative values have not been tested. Secondly, it is most likely that to determine appropriate values for these arguments, users will have to investigate the code for xtableFtable and/or print.xtableFtable.

Author(s)

David Scott [e-mail].

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

See Also

ftable, print.ftable

xtable, caption, label, align, digits, display, formatC

Examples

data(mtcars)
mtcars$cyl <- factor(mtcars$cyl, levels = c("4","6","8"),
                     labels = c("four","six","eight"))
tbl <- ftable(mtcars$cyl, mtcars$vs, mtcars$am, mtcars$gear,
              row.vars = c(2, 4),
              dnn = c("Cylinders", "V/S", "Transmission", "Gears"))
xftbl <- xtableFtable(tbl, method = "compact")
print.xtableFtable(xftbl, booktabs = TRUE)
xftbl <- xtableFtable(tbl, method = "row.compact")
print.xtableFtable(xftbl, rotate.colnames = TRUE,
                   rotate.rownames = TRUE)