From: dscott Date: Tue, 26 Jan 2016 04:52:43 +0000 (+0000) Subject: Forgot to add .Rd file. Adding now X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=bbec4e89581c9b87265a2309e55c303d77ff49ab;p=xtable.git Forgot to add .Rd file. Adding now git-svn-id: svn://scm.r-forge.r-project.org/svnroot/xtable@100 edb9625f-4e0d-4859-8d74-9fd3b1da38cb --- diff --git a/pkg/man/xtableFtable.Rd b/pkg/man/xtableFtable.Rd new file mode 100644 index 0000000..69c4a98 --- /dev/null +++ b/pkg/man/xtableFtable.Rd @@ -0,0 +1,342 @@ +\name{xtableFtable} +\alias{xtableFtable} +\alias{print.xtableFtable} + +\title{ + Create and Export Flat Tables +} +\description{ + \code{xtableFtable} creates an object which contains information about + a flat table which can be used by \code{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 = " | ", ...) + +\method{print}{xtableFtable}(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", 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{ + \item{x}{For \code{xtableFtable}, an object of class + \code{"ftable"}. For \code{print.xtableFtable}, an object of class + \code{c("xtableFtable", "ftable")}.} + \item{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 + \code{NULL} to suppress the caption. Default value is \code{NULL}. } + \item{label}{Character vector of length 1 containing the LaTeX label + or HTML anchor. Set to \code{NULL} to suppress the label. Default + value is \code{NULL}. } + \item{align}{Character vector of length equal to the number of columns + of the resulting table, indicating the alignment of the corresponding + columns. Also, \code{"|"} 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 + \code{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 \code{"l"}, \code{"r"}, and \code{"c"} to + denote left, right, and center alignment, respectively. Use + \code{"p{3cm}"} etc. for a LaTeX column of the specified width. For + HTML output the \code{"p"} alignment is interpreted as \code{"l"}, + ignoring the width request. + If \code{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 \code{align} + depends on the value of \code{method}.} + \item{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 \code{digits} is negative, the + corresponding columns are displayed in scientific format + with \code{abs(digits)} digits.} + \item{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 \code{formatC} + function. Use \code{"d"} (for integers), \code{"f"}, \code{"e"}, + \code{"E"}, \code{"g"}, \code{"G"}, \code{"fg"} (for reals), or + \code{"s"} (for strings). \code{"f"} gives numbers in the usual + \code{xxx.xxx} format; \code{"e"} and \code{"E"} give + \code{n.ddde+nn} or \code{n.dddE+nn} (scientific format); \code{"g"} + and \code{"G"} put \code{x[i]} into scientific format only if it + saves space to do so. \code{"fg"} uses fixed format as \code{"f"}, + but \code{digits} as number of \emph{significant} digits. Note that + this can lead to quite long result strings. + If \code{NULL} all row variable names and labels will have format + \code{"s"}, and all data columns will have format \code{"d"}. The + actual length of \code{display} depends on the value of + \code{method}.} + \item{quote}{a character string giving the set of quoting characters + for \code{format.ftable} used in \code{print.xtableFtable}; to + disable quoting altogether, use \code{quote=""}.} + + \item{method}{string specifying how the \code{"xtableFtable"} object is + printed in the \code{print} method. Can be abbreviated. Available + methods are (see the examples in \code{\link{print.ftable}}): + \describe{ + \item{"non.compact"}{the default representation of an + \code{"ftable"} object.} + \item{"row.compact"}{a row-compact version without empty cells + below the column labels.} + \item{"col.compact"}{a column-compact version without empty cells + to the right of the row labels.} + \item{"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 \code{lsep}.} + } + } + \item{lsep}{only for \code{method = "compact"}, the separation string + for row and column labels.} + \item{type}{Type of table to produce. Possible values for \code{type} + are \code{"latex"} or \code{"html"}. + Default value is \code{"latex"} and is the only type implemented so far.} + \item{file}{Name of file where the resulting code should be saved. If + \code{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 \code{""}.} + \item{append}{If \code{TRUE} and \code{file!=""}, code will be + appended to \code{file} instead of overwriting \code{file}. + Default value is \code{FALSE}.} + \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting + table will be a floating table (using, for example, + \code{\\begin\{table\}} and \code{\\end\{table\}}). See + \code{floating.environment} below. + Default value is \code{TRUE}. } + \item{floating.environment}{If \code{floating=TRUE} and + \code{type="latex"}, the resulting table uses the specified floating + environment. Possible values include \code{"table"}, \code{"table*"}, + and other floating environments defined in LaTeX packages. + Default value is \code{"table"}.} + \item{table.placement}{If \code{floating=TRUE} and + \code{type="latex"}, the floating table will have placement given by + \code{table.placement} where \code{table.placement} must be + \code{NULL} or contain only elements of + \{"h","t","b","p","!","H"\}. + Default value is \code{"ht"}.} + \item{caption.placement}{The caption will be placed at the bottom + of the table if \code{caption.placement} is \code{"bottom"} and at + the top of the table if it equals \code{"top"}. + Default value is \code{"bottom"}.} + \item{caption.width}{The caption will be placed in a \code{"parbox"} + of the specified width if \code{caption.width} is not \code{NULL} and + \code{type="latex"}. Default value is \code{NULL}.} + \item{latex.environments}{If \code{floating=TRUE} and + \code{type="latex"}, the specified LaTeX environments (provided as + a character vector) will enclose the tabular environment. + Default value is \code{"center"}. } + \item{tabular.environment}{When \code{type="latex"}, the tabular + environment that will be used. + When working with tables that extend more than one page, using + \code{tabular.environment="longtable"} with the corresponding + LaTeX package (see Fairbairns, 2005) allows one to typeset them + uniformly. Note that \code{floating} should be set to + \code{FALSE} when using the \code{longtable} environment. + Default value is \code{"tabular"}.} + \item{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 \code{NULL}. } + \item{hline.after}{When \code{type="latex"}, a vector of numbers + between -1 and \code{nrow(x)}, inclusive, indicating the rows after + which a horizontal line should appear. Repeated values are + allowed. If \code{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.} + \item{NA.string}{String to be used for missing values in table + entries. + Default value is \code{""}.} + \item{only.contents}{If \code{TRUE} only the rows of the + table are printed. + Default value is \code{FALSE}. } + \item{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 \code{NULL}, i.e. do not add commands.} + \item{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 + \code{sanitize.text.function} is not \code{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 \code{NULL}.} + \item{sanitize.rownames.function}{Like the + \code{sanitize.text.function}, but applicable to row names. + The default uses the \code{sanitize.text.function}. } + \item{sanitize.colnames.function}{Like the + \code{sanitize.text.function}, but applicable to column names. + The default uses the \code{sanitize.text.function}. } + \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use + $-$ for the negative sign (as was the behavior prior to version 1.5-3). + Default value is \code{FALSE}.} + \item{math.style.exponents}{In a LaTeX table, if \code{TRUE} or + \code{"$$"}, then use \verb{$5 \times 10^{5}$} for 5e5. If + \code{"ensuremath"}, then use \verb{\\ensuremath{5 \times 10^{5}}} + for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to + approximate the LaTeX typsetting for 5e5. + Default value is \code{FALSE}.} + \item{html.table.attributes}{In an HTML table, attributes associated + with the \code{} tag. + Default value is \code{"border=1"}.} + \item{print.results}{If \code{TRUE}, the generated table is printed to + standard output. Set this to \code{FALSE} if you will just be using + the character vector that is returned invisibly. + Default value is \code{TRUE}.} + \item{format.args}{List of arguments for the \code{formatC} function. + For example, standard German number separators can be specified as + \code{format.args=list(big.mark = "'", decimal.mark = + ","))}. The arguments \code{digits} and \code{format} should not be + included in this list. + Default value is \code{NULL}.} + \item{rotate.rownames}{If \code{TRUE}, the row names and labels, and + column variable names are displayed vertically in LaTeX. + Default value is \code{FALSE}.} + \item{rotate.colnames}{If \code{TRUE}, the column names and labels, + and row variable names are displayed vertically in LaTeX. + Default value is \code{FALSE}.} + \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and + \code{bottomrule} commands from the LaTeX "booktabs" package are used + rather than \code{hline} for the horizontal line tags. } + \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be + added around the tabular environment with the specified value used + as the scaling factor. + Default value is \code{NULL}.} + \item{width}{If not \code{NULL}, the specified value is included in + parentheses between the tabular environment \code{begin} tag and the + alignment specification. This allows specification of the table + width when using tabular environments such as \code{tabular*} and + \code{tabularx}. Note that table width specification is not + supported with the \code{tabular} or \code{longtable} environments. + Default value is \code{NULL}.} + \item{comment}{If \code{TRUE}, the version and timestamp comment is + included. Default value is \code{TRUE}. } + \item{timestamp}{Timestamp to include in LaTeX comment. Set this + to \code{NULL} to exclude the timestamp. Default value is \code{date()}. } + \item{...}{Additional arguments. (Currently ignored.) } +} +\details{ + \code{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 + \code{method}. It uses the results of those calculations to set + sensible values for \code{align} and \code{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 + \code{c("xtableFtable", "ftable")}. + + \code{print.xtableFtable} uses the attributes attached to an object + of class \code{c("xtableFtable", "ftable")} to create a suitable + character matrix object for subsequent printing via a call to + \code{stats:::format.ftable}. This matrix object is then printed via + a call to \code{print.xtable}. + + Note that at present there is no code for \code{type = "html"}. +} +\value{ + For \code{xtableFtable} an object of class \code{c("xtableFtable", + "ftable")}, with attributes + \item{ftableCaption}{the value of the \code{caption} argument} + \item{ftableLabel}{the value of the \code{label} argument} + \item{ftableAlign}{the value of the \code{label} argument} + \item{ftableDigits}{the value of the \code{digits} argument or the + default value if \code{digits = NULL}} + \item{quote}{the value of the \code{quote} argument} + \item{ftableDisplay}{the value of the \code{display} argument or the + default value if \code{align = NULL}} + \item{method}{the value of the \code{method} argument} + \item{lsep}{the value of the \code{lsep} argument} + \item{nChars}{a vector of length 2 giving the number of character rows + and the number of character columns} + + For \code{print.xtableFtable} a character string which will produce a + formatted table when included in a LaTeX document. + +} +\references{ + Fairbairns, Robin (2005) \emph{Tables longer than a single page.} The + UK List of TeX Frequently Asked Questions on the + Web. \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=longtab} +} +\author{ + David Scott \email{d.scott@auckland.ac.nz}. +} +\note{ + It is not recommended that users change the values of \code{align}, + \code{digits} or \code{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 \code{xtableFtable} and/or \code{print.xtableFtable}. +} + +\seealso{ + \code{\link{ftable}}, \code{\link{print.ftable}}, + \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}}, + \code{\link{align}}, \code{\link{digits}}, \code{\link{display}}, + \code{\link{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) +} + +\keyword{ category } +\keyword{ print }