pkg/man/xtableFtable.Rd

   1 \name{xtableFtable}
   2 \alias{xtableFtable}
   3 \alias{print.xtableFtable}
   4
   5 \title{
   6   Create and Export Flat Tables
   7 }
   8 \description{
   9   \code{xtableFtable} creates an object which contains information about
  10   a flat table which can be used by \code{print.xtableFtable} to produce
  11   a character string which when included in a document produces a nicely
  12   formatted flat table.
  13 }
  14 \usage{
  15 xtableFtable(x, caption = NULL, label = NULL,
  16              align = NULL, digits = 0, display = NULL,
  17              quote = FALSE,
  18              method = c("non.compact", "row.compact",
  19                          "col.compact", "compact"),
  20              lsep = " $\\\\vert$ ", ...)
  21
  22 \method{print}{xtableFtable}(x,
  23   type = getOption("xtable.type", "latex"),
  24   file = getOption("xtable.file", ""),
  25   append = getOption("xtable.append", FALSE),
  26   floating = getOption("xtable.floating", TRUE),
  27   floating.environment = getOption("xtable.floating.environment", "table"),
  28   table.placement = getOption("xtable.table.placement", "ht"),
  29   caption.placement = getOption("xtable.caption.placement", "bottom"),
  30   caption.width = getOption("xtable.caption.width", NULL),
  31   latex.environments = getOption("xtable.latex.environments", c("center")),
  32   tabular.environment = getOption("xtable.tabular.environment", "tabular"),
  33   size = getOption("xtable.size", NULL),
  34   hline.after = getOption("xtable.hline.after", NULL),
  35   NA.string = getOption("xtable.NA.string", ""),
  36   only.contents = getOption("xtable.only.contents", FALSE),
  37   add.to.row = getOption("xtable.add.to.row", NULL),
  38   sanitize.text.function = getOption("xtable.sanitize.text.function", as.is),
  39   sanitize.rownames.function = getOption("xtable.sanitize.rownames.function",
  40                                          sanitize.text.function),
  41   sanitize.colnames.function = getOption("xtable.sanitize.colnames.function",
  42                                          sanitize.text.function),
  43   math.style.negative = getOption("xtable.math.style.negative", FALSE),
  44   math.style.exponents = getOption("xtable.math.style.exponents", FALSE),
  45   html.table.attributes = getOption("xtable.html.table.attributes",
  46                                     "border=1"),
  47   print.results = getOption("xtable.print.results", TRUE),
  48   format.args = getOption("xtable.format.args", NULL),
  49   rotate.rownames = getOption("xtable.rotate.rownames", FALSE),
  50   rotate.colnames = getOption("xtable.rotate.colnames", FALSE),
  51   booktabs = getOption("xtable.booktabs", FALSE),
  52   scalebox = getOption("xtable.scalebox", NULL),
  53   width = getOption("xtable.width", NULL),
  54   comment = getOption("xtable.comment", TRUE),
  55   timestamp = getOption("xtable.timestamp", date()),
  56   ...)
  57 }
  58
  59 \arguments{
  60   \item{x}{For \code{xtableFtable}, an object of class
  61   \code{"ftable"}. For \code{print.xtableFtable}, an object of class
  62   \code{c("xtableFtable", "ftable")}.}
  63   \item{caption}{Character vector of length 1 or 2 containing the
  64     table's caption or title.  If length is 2, the second item is the
  65     "short caption" used when LaTeX generates a "List of Tables". Set to
  66     \code{NULL} to suppress the caption.  Default value is \code{NULL}. }
  67   \item{label}{Character vector of length 1 containing the LaTeX label
  68     or HTML anchor. Set to \code{NULL} to suppress the label.  Default
  69     value is \code{NULL}. }
  70   \item{align}{Character vector of length equal to the number of columns
  71     of the resulting table, indicating the alignment of the corresponding
  72     columns.  Also, \code{"|"} may be used to produce vertical lines
  73     between columns in LaTeX tables, but these are effectively ignored
  74     when considering the required length of the supplied vector.  If a
  75     character vector of length one is supplied, it is split as
  76     \code{strsplit(align, "")[[1]]} before processing. For a flat table,
  77     the number of columns is the number of columns of data, plus the
  78     number of row variables in the table, plus one for the row names,
  79     even though row names are not printed.
  80     Use \code{"l"}, \code{"r"}, and \code{"c"} to
  81     denote left, right, and center alignment, respectively.  Use
  82     \code{"p{3cm}"} etc. for a LaTeX column of the specified width. For
  83     HTML output the \code{"p"} alignment is interpreted as \code{"l"},
  84     ignoring the width request.
  85     If \code{NULL} all row variable labels will be left aligned,
  86     separated from the data columns by a vertical line, and all data
  87     columns will be right aligned. The actual length of \code{align}
  88     depends on the value of \code{method}.}
  89   \item{digits}{
  90     Numeric vector of length equal to one (in which case it will be
  91     replicated as necessary) or to the number of columns in the
  92     resulting table. Since data in the table consists of
  93     counts, the default is 0. If the value of \code{digits} is negative, the
  94     corresponding columns are displayed in scientific format
  95     with \code{abs(digits)} digits.}
  96   \item{display}{
  97     Character vector of length equal to the number of columns of the
  98     resulting table, indicating the format for the corresponding columns.
  99     These values are passed to the \code{formatC}
 100     function.  Use \code{"d"} (for integers), \code{"f"}, \code{"e"},
 101     \code{"E"}, \code{"g"}, \code{"G"}, \code{"fg"} (for reals), or
 102     \code{"s"} (for strings).  \code{"f"} gives numbers in the usual
 103     \code{xxx.xxx} format; \code{"e"} and \code{"E"} give
 104     \code{n.ddde+nn} or \code{n.dddE+nn} (scientific format); \code{"g"}
 105     and \code{"G"} put \code{x[i]} into scientific format only if it
 106     saves space to do so.  \code{"fg"} uses fixed format as \code{"f"},
 107     but \code{digits} as number of \emph{significant} digits.  Note that
 108     this can lead to quite long result strings.
 109     If \code{NULL} all row variable names and labels will have format
 110     \code{"s"}, and all data columns will have format \code{"d"}. The
 111     actual length of \code{display} depends on the value of
 112     \code{method}.}
 113   \item{quote}{a character string giving the set of quoting characters
 114     for \code{format.ftable} used in \code{print.xtableFtable}; to
 115     disable quoting altogether, use \code{quote=""}.}
 116
 117   \item{method}{string specifying how the \code{"xtableFtable"} object is
 118     printed in the \code{print} method.  Can be abbreviated.  Available
 119     methods are (see the examples in \code{\link{print.ftable}}):
 120     \describe{
 121       \item{"non.compact"}{the default representation of an
 122         \code{"ftable"} object.}
 123       \item{"row.compact"}{a row-compact version without empty cells
 124         below the column labels.}
 125       \item{"col.compact"}{a column-compact version without empty cells
 126         to the right of the row labels.}
 127       \item{"compact"}{a row- and column-compact version.  This may imply
 128         a row and a column label sharing the same cell.  They are then
 129         separated by the string \code{lsep}.}
 130     }
 131   }
 132   \item{lsep}{only for \code{method = "compact"}, the separation string
 133     for row and column labels.}
 134   \item{type}{Type of table to produce. Possible values for \code{type}
 135     are \code{"latex"} or \code{"html"}.
 136     Default value is \code{"latex"} and is the only type implemented so far.}
 137   \item{file}{Name of file where the resulting code should be saved.  If
 138     \code{file=""}, output is displayed on screen.  Note that the
 139     function also (invisibly) returns a character vector of the results
 140     (which can be helpful for post-processing).
 141     Default value is \code{""}.}
 142   \item{append}{If \code{TRUE} and \code{file!=""}, code will be
 143     appended to \code{file} instead of overwriting \code{file}.
 144     Default value is \code{FALSE}.}
 145   \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting
 146     table will be a floating table (using, for example,
 147     \code{\\begin\{table\}} and \code{\\end\{table\}}).  See
 148     \code{floating.environment} below.
 149     Default value is \code{TRUE}. }
 150   \item{floating.environment}{If \code{floating=TRUE} and
 151     \code{type="latex"}, the resulting table uses the specified floating
 152     environment. Possible values include \code{"table"}, \code{"table*"},
 153     and other floating environments defined in LaTeX packages.
 154     Default value is \code{"table"}.}
 155   \item{table.placement}{If \code{floating=TRUE} and
 156     \code{type="latex"}, the floating table will have placement given by
 157     \code{table.placement} where \code{table.placement} must be
 158     \code{NULL} or contain only elements of
 159     \{"h","t","b","p","!","H"\}.
 160     Default value is \code{"ht"}.}
 161   \item{caption.placement}{The caption will be placed at the bottom
 162     of the table if \code{caption.placement} is \code{"bottom"} and at
 163     the top of the table if it equals \code{"top"}.
 164     Default value is \code{"bottom"}.}
 165   \item{caption.width}{The caption will be placed in a \code{"parbox"}
 166     of the specified width if \code{caption.width} is not \code{NULL} and
 167         \code{type="latex"}. Default value is \code{NULL}.}
 168   \item{latex.environments}{If \code{floating=TRUE} and
 169     \code{type="latex"}, the specified LaTeX environments (provided as
 170     a character vector) will enclose the tabular environment.
 171     Default value is \code{"center"}. }
 172   \item{tabular.environment}{When \code{type="latex"}, the tabular
 173     environment that will be used.
 174     When working with tables that extend more than one page, using
 175     \code{tabular.environment="longtable"} with the corresponding
 176     LaTeX package (see Fairbairns, 2005) allows one to typeset them
 177     uniformly. Note that \code{floating} should be set to
 178     \code{FALSE} when using the \code{longtable} environment.
 179     Default value is \code{"tabular"}.}
 180   \item{size}{A character vector that is inserted just before the
 181     tabular environment starts. This can be used to set the font size
 182     and a variety of other table settings. Initial backslashes are
 183     automatically prefixed, if not supplied by user.
 184     Default value is \code{NULL}. }
 185   \item{hline.after}{When \code{type="latex"}, a vector of numbers
 186     between -1 and \code{nrow(x)}, inclusive, indicating the rows after
 187     which a horizontal line should appear.  Repeated values are
 188     allowed. If \code{NULL} the default is to draw a line before before
 189     starting the table, after the column variable names and labels, and
 190     at the end of the table.}
 191   \item{NA.string}{String to be used for missing values in table
 192     entries.
 193     Default value is \code{""}.}
 194  \item{only.contents}{If \code{TRUE} only the rows of the
 195     table are printed.
 196     Default value is \code{FALSE}. }
 197   \item{add.to.row}{A list of two components. The first component (which
 198     should be called 'pos') is a list that contains the position of rows on
 199     which extra commands should be added at the end. The second
 200     component (which should be called 'command') is a character vector
 201     of the same length as the first component, which contains the command
 202     that should be added at the end of the specified rows.
 203     Default value is \code{NULL}, i.e. do not add commands.}
 204   \item{sanitize.text.function}{Since the table entries are counts no
 205     sanitization is necessary. The default is \code{as.is}, which is the
 206     function which makes no changes. This also applies to the labels for
 207     the row and column variables since these are also part of the table
 208     which is printed using a call to \code{print.xtable}.}
 209   \item{sanitize.rownames.function}{Like the
 210     \code{sanitize.text.function}, but applicable to row names.
 211     The default uses the \code{sanitize.text.function}. }
 212   \item{sanitize.colnames.function}{Like the
 213     \code{sanitize.text.function}, but applicable to column names.
 214     The default uses the \code{sanitize.text.function}. }
 215   \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use
 216     $-$ for the negative sign (as was the behavior prior to version 1.5-3).
 217     Default value is \code{FALSE}.}
 218   \item{math.style.exponents}{In a LaTeX table, if \code{TRUE} or
 219     \code{"$$"}, then use \verb{$5 \times 10^{5}$} for 5e5. If
 220     \code{"ensuremath"}, then use \verb{\\ensuremath{5 \times 10^{5}}}
 221     for 5e5. If \code{"UTF-8"} or \code{"UTF-8"}, then use UTF-8 to
 222     approximate the LaTeX typsetting for 5e5.
 223     Default value is \code{FALSE}.}
 224   \item{html.table.attributes}{In an HTML table, attributes associated
 225     with the \code{<TABLE>} tag.
 226     Default value is \code{"border=1"}.}
 227   \item{print.results}{If \code{TRUE}, the generated table is printed to
 228     standard output.  Set this to \code{FALSE} if you will just be using
 229     the character vector that is returned invisibly.
 230   Default value is \code{TRUE}.}
 231   \item{format.args}{List of arguments for the \code{formatC} function.
 232     For example, standard German number separators can be specified as
 233     \code{format.args=list(big.mark = "'", decimal.mark =
 234       ","))}. The arguments \code{digits} and \code{format} should not be
 235     included in this list.
 236     Default value is \code{NULL}.}
 237   \item{rotate.rownames}{If \code{TRUE}, the row names and labels, and
 238     column variable names are displayed vertically in LaTeX.
 239     Default value is \code{FALSE}.}
 240   \item{rotate.colnames}{If \code{TRUE}, the column names and labels,
 241     and row variable names are displayed vertically in LaTeX.
 242     Default value is \code{FALSE}.}
 243   \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and
 244     \code{bottomrule} commands from the LaTeX "booktabs" package are used
 245     rather than \code{hline} for the horizontal line tags. }
 246   \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be
 247     added around the tabular environment with the specified value used
 248     as the scaling factor.
 249     Default value is \code{NULL}.}
 250   \item{width}{If not \code{NULL}, the specified value is included in
 251     parentheses between the tabular environment \code{begin} tag and the
 252     alignment specification.  This allows specification of the table
 253     width when using tabular environments such as \code{tabular*} and
 254     \code{tabularx}.  Note that table width specification is not
 255     supported with the \code{tabular} or \code{longtable} environments.
 256     Default value is \code{NULL}.}
 257   \item{comment}{If \code{TRUE}, the version and timestamp comment is
 258     included.  Default value is \code{TRUE}. }
 259   \item{timestamp}{Timestamp to include in LaTeX comment.  Set this
 260     to \code{NULL} to exclude the timestamp. Default value is
 261     \code{date()}. }
 262   \item{...}{Additional arguments.  (Currently ignored.) }
 263 }
 264 \details{
 265   \code{xtableFtable} carries out some calculations to determine the
 266     number of rows and columns of names and labels which will be in the
 267     table when formatted as a flat table, which depends on the value of
 268     \code{method}. It uses the results of those calculations to set
 269     sensible values for \code{align} and \code{display} if these have
 270     not been supplied. It attaches attributes to the resulting object
 271     which specify details of the function call which are needed when
 272     printing the resulting object which is of class
 273     \code{c("xtableFtable", "ftable")}.
 274
 275     \code{print.xtableFtable} uses the attributes attached to an object
 276     of class \code{c("xtableFtable", "ftable")} to create a suitable
 277     character matrix object for subsequent printing via a call to
 278     \code{stats:::format.ftable}. This matrix object is then printed via
 279     a call to \code{print.xtable}.
 280
 281     Note that at present there is no code for \code{type = "html"}.
 282 }
 283 \value{
 284   For \code{xtableFtable} an object of class \code{c("xtableFtable",
 285     "ftable")}, with attributes
 286   \item{ftableCaption}{the value of the \code{caption} argument}
 287   \item{ftableLabel}{the value of the \code{label} argument}
 288   \item{ftableAlign}{the value of the \code{label} argument}
 289   \item{ftableDigits}{the value of the \code{digits} argument or the
 290     default value if \code{digits = NULL}}
 291   \item{quote}{the value of the \code{quote} argument}
 292   \item{ftableDisplay}{the value of the \code{display} argument or the
 293     default value if \code{align = NULL}}
 294   \item{method}{the value of the \code{method} argument}
 295   \item{lsep}{the value of the \code{lsep} argument}
 296   \item{nChars}{a vector of length 2 giving the number of character rows
 297     and the number of character columns}
 298
 299   For \code{print.xtableFtable} a character string which will produce a
 300   formatted table when included in a LaTeX document.
 301
 302 }
 303 \references{
 304   Fairbairns, Robin (2005) \emph{Tables longer than a single page.} The
 305   UK List of TeX Frequently Asked Questions on the
 306   Web. \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=longtab}
 307 }
 308 \author{
 309   David Scott \email{d.scott@auckland.ac.nz}.
 310 }
 311 \note{
 312   The functions \code{xtableFtable} and \code{print.xtableFtable} are
 313   new and their behaviour may change in the future based on user
 314   experience and recommendations.
 315
 316   It is not recommended that users change the values of \code{align},
 317   \code{digits} or \code{align}. First of all, alternative values have
 318   not been tested. Secondly, it is most likely that to determine
 319   appropriate values for these arguments, users will have to investigate
 320   the code for \code{xtableFtable} and/or \code{print.xtableFtable}.
 321 }
 322
 323 \seealso{
 324   \code{\link{ftable}}, \code{\link{print.ftable}},
 325   \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}},
 326   \code{\link{align}}, \code{\link{digits}}, \code{\link{display}},
 327   \code{\link{formatC}}
 328 }
 329 \examples{
 330 data(mtcars)
 331 mtcars$cyl <- factor(mtcars$cyl, levels = c("4","6","8"),
 332                      labels = c("four","six","eight"))
 333 tbl <- ftable(mtcars$cyl, mtcars$vs, mtcars$am, mtcars$gear,
 334               row.vars = c(2, 4),
 335               dnn = c("Cylinders", "V/S", "Transmission", "Gears"))
 336 xftbl <- xtableFtable(tbl, method = "compact")
 337 print.xtableFtable(xftbl, booktabs = TRUE)
 338 xftbl <- xtableFtable(tbl, method = "row.compact")
 339 print.xtableFtable(xftbl, rotate.colnames = TRUE,
 340                    rotate.rownames = TRUE)
 341 }
 342
 343 \keyword{ category }
 344 \keyword{ print }