pkg/man/xtable.Rd

   1 \name{xtable}
   2 \alias{xtable}
   3 \alias{xtable.anova}
   4 \alias{xtable.aov}
   5 \alias{xtable.aovlist}
   6 \alias{xtable.data.frame}
   7 \alias{xtable.glm}
   8 \alias{xtable.lm}
   9 \alias{xtable.matrix}
  10 \alias{xtable.xtableMatharray}
  11 \alias{xtable.prcomp}
  12 \alias{xtable.coxph}
  13 \alias{xtable.summary.aov}
  14 \alias{xtable.summary.aovlist}
  15 \alias{xtable.summary.glm}
  16 \alias{xtable.summary.lm}
  17 \alias{xtable.summary.prcomp}
  18 \alias{xtable.ts}
  19 \alias{xtable.table}
  20 \alias{xtable.zoo}
  21 \alias{xtable.sarlm}
  22 \alias{xtable.summary.sarlm}
  23 \alias{xtable.gmsar}
  24 \alias{xtable.summary.gmsar}
  25 \alias{xtable.stsls}
  26 \alias{xtable.summary.stsls}
  27 \alias{xtable.splm}
  28 \alias{xtable.summary.splm}
  29 \alias{xtable.sphet}
  30 \alias{xtable.summary.sphet}
  31
  32
  33
  34 \title{Create Export Tables}
  35 \description{
  36   Convert an R object to an \code{xtable} object, which can
  37   then be printed as a LaTeX or HTML table.
  38 }
  39 \usage{
  40 xtable(x, caption = NULL, label = NULL, align = NULL, digits = NULL,
  41        display = NULL, auto = FALSE, ...)
  42 }
  43 \arguments{
  44   \item{x}{An R object of class found among \code{methods(xtable)}.  See
  45     below on how to write additional method functions for \code{xtable}.}
  46   \item{caption}{Character vector of length 1 or 2 containing the
  47     table's caption or title.  If length is 2, the second item is the
  48     "short caption" used when LaTeX generates a "List of Tables". Set to
  49     \code{NULL} to suppress the caption.  Default value is \code{NULL}. }
  50   \item{label}{Character vector of length 1 containing the LaTeX label
  51     or HTML anchor. Set to \code{NULL} to suppress the label.  Default
  52     value is \code{NULL}. }
  53   \item{align}{Character vector of length equal to the number of columns
  54     of the resulting table, indicating the alignment of the corresponding
  55     columns.  Also, \code{"|"} may be used to produce vertical lines
  56     between columns in LaTeX tables, but these are effectively ignored
  57     when considering the required length of the supplied vector.  If a
  58     character vector of length one is supplied, it is split as
  59     \code{strsplit(align, "")[[1]]} before processing. Since the row
  60     names are printed in the first column, the length of \code{align} is
  61     one greater than \code{ncol(x)} if \code{x} is a
  62     \code{data.frame}. Use \code{"l"}, \code{"r"}, and \code{"c"} to
  63     denote left, right, and center alignment, respectively.  Use
  64     \code{"p{3cm}"} etc. for a LaTeX column of the specified width. For
  65     HTML output the \code{"p"} alignment is interpreted as \code{"l"},
  66     ignoring the width request. Default depends on the class of
  67     \code{x}. }
  68   \item{digits}{
  69     Numeric vector of length equal to one (in which case it will be
  70     replicated as necessary) or to the number of columns of the
  71     resulting table \bold{or} matrix of the same size as the resulting
  72     table, indicating the number of digits to display in the
  73     corresponding columns. Since the row names are printed in the first
  74     column, the length of the vector \code{digits} or the number of
  75     columns of the matrix \code{digits} is one greater than
  76     \code{ncol(x)} if \code{x} is a \code{data.frame}. Default depends
  77     on the class of \code{x}. If values of \code{digits} are negative, the
  78     corresponding values of \code{x} are displayed in scientific format
  79     with \code{abs(digits)} digits.}
  80   \item{display}{
  81     Character vector of length equal to the number of columns of the
  82     resulting table, indicating the format for the corresponding columns.
  83     Since the row names are printed in the first column, the length of
  84     \code{display} is one greater than \code{ncol(x)} if \code{x} is a
  85     \code{data.frame}.  These values are passed to the \code{formatC}
  86     function.  Use \code{"d"} (for integers), \code{"f"}, \code{"e"},
  87     \code{"E"}, \code{"g"}, \code{"G"}, \code{"fg"} (for reals), or
  88     \code{"s"} (for strings).  \code{"f"} gives numbers in the usual
  89     \code{xxx.xxx} format; \code{"e"} and \code{"E"} give
  90     \code{n.ddde+nn} or \code{n.dddE+nn} (scientific format); \code{"g"}
  91     and \code{"G"} put \code{x[i]} into scientific format only if it
  92     saves space to do so.  \code{"fg"} uses fixed format as \code{"f"},
  93     but \code{digits} as number of \emph{significant} digits.  Note that
  94     this can lead to quite long result strings.  Default depends on the
  95     class of \code{x}.}
  96   \item{auto}{
  97     Logical, indicating whether to apply automatic format when no value
  98     is passed to \code{align}, \code{digits}, or \code{display}. This
  99     \sQuote{autoformat} (based on \code{xalign}, \code{xdigits}, and
 100     \code{xdisplay}) can be useful to quickly format a typical
 101     \code{matrix} or \code{data.frame}. Default value is \code{FALSE}.}
 102   \item{...}{Additional arguments.  (Currently ignored.)}
 103 }
 104 \details{
 105
 106   This function extracts tabular information from \code{x} and returns
 107   an object of class \code{"xtable"}.  The nature of the table generated
 108   depends on the class of \code{x}.  For example, \code{aov} objects
 109   produce ANOVA tables while \code{data.frame} objects produce a table
 110   of the entire data frame.  One can optionally provide a caption
 111   or label (called an anchor in HTML), as well
 112   as formatting specifications.  Default values for \code{align},
 113   \code{digits}, and \code{display} are class dependent.
 114
 115   The available method functions for \code{xtable} are given by
 116   \code{methods(xtable)}.  Users can extend the list of available
 117   classes by writing methods for the generic function \code{xtable}.
 118   These methods functions should have \code{x} as their first argument,
 119   with additional arguments to specify \code{caption}, \code{label},
 120   \code{align}, \code{digits}, and \code{display}.  Optionally, other
 121   arguments may be passed to specify how the object \code{x} should be
 122   manipulated.  All method functions should return an object whose class
 123   is \code{c("xtable","data.frame")}.  The resulting object can
 124   have attributes \code{caption} and \code{label}, but must have
 125   attributes \code{align}, \code{digits}, and \code{display}.
 126 }
 127 \value{
 128   For most \code{xtable} methods, an object of class \code{"xtable"}
 129   which inherits the \code{data.frame} class and contains several
 130   additional attributes specifying the table formatting options.
 131
 132   In the case of the \code{xtableMatharray} method, an object of class
 133   \code{xtableMatharray}, which the \code{xtable} and \code{data.frame}
 134   classes and contains several additional attributes specifying the
 135   table formatting options.
 136
 137 }
 138 \author{David Dahl \email{dahl@stat.byu.edu} with contributions and
 139   suggestions from many others (see source code).
 140 }
 141 \seealso{
 142   \code{\link{print.xtable}}, \code{\link{caption}},
 143   \code{\link{label}}, \code{\link{align}}, \code{\link{digits}},
 144   \code{\link{display}}
 145
 146   \code{\link{autoformat}}, \code{\link{xalign}}, \code{\link{xdigits}},
 147   \code{\link{xdisplay}}
 148 }
 149 \examples{
 150
 151 ## Load example dataset
 152 data(tli)
 153
 154 ## Demonstrate data.frame
 155 tli.table <- xtable(tli[1:20, ])
 156 print(tli.table)
 157 print(tli.table, type = "html")
 158 xtable(mtcars)
 159 xtable(mtcars, auto = TRUE)
 160
 161 ## Demonstrate data.frame with different digits in cells
 162 tli.table <- xtable(tli[1:20, ])
 163 display(tli.table)[c(2,6)] <- "f"
 164 digits(tli.table) <- matrix(0:4, nrow = 20, ncol = ncol(tli)+1)
 165 print(tli.table)
 166 print(tli.table, type = "html")
 167
 168 ## Demonstrate matrix
 169 design.matrix <- model.matrix(~ sex*grade, data = tli[1:20, ])
 170 design.table <- xtable(design.matrix, auto = TRUE)
 171 print(design.table)
 172 print(design.table, type = "html")
 173
 174 ## Demonstrate aov
 175 fm1 <- aov(tlimth ~ sex + ethnicty + grade + disadvg, data = tli)
 176 fm1.table <- xtable(fm1)
 177 print(fm1.table)
 178 print(fm1.table, type = "html")
 179
 180 ## Demonstrate lm
 181 fm2 <- lm(tlimth ~ sex*ethnicty, data = tli)
 182 fm2.table <- xtable(fm2)
 183 print(fm2.table)
 184 print(fm2.table, type = "html")
 185 print(xtable(anova(fm2)))
 186 print(xtable(anova(fm2)), type = "html")
 187 fm2b <- lm(tlimth ~ ethnicty, data = tli)
 188 print(xtable(anova(fm2b, fm2)))
 189 print(xtable(anova(fm2b, fm2)), type = "html")
 190
 191 ## Demonstrate glm
 192 fm3 <- glm(disadvg ~ ethnicty*grade, data = tli, family = binomial())
 193 fm3.table <- xtable(fm3)
 194 print(fm3.table)
 195 print(fm3.table, type = "html")
 196 print(xtable(anova(fm3)))
 197 print(xtable(anova(fm3)), type = "html")
 198
 199 ## Demonstrate aov
 200 ## Taken from help(aov) in R 1.1.1
 201 ## From Venables and Ripley (1997) p.210.
 202 N <- c(0,1,0,1,1,1,0,0,0,1,1,0,1,1,0,0,1,0,1,0,1,1,0,0)
 203 P <- c(1,1,0,0,0,1,0,1,1,1,0,0,0,1,0,1,1,0,0,1,0,1,1,0)
 204 K <- c(1,0,0,1,0,1,1,0,0,1,0,1,0,1,1,0,0,0,1,1,1,0,1,0)
 205 yield <- c(49.5,62.8,46.8,57.0,59.8,58.5,55.5,56.0,62.8,55.8,69.5,55.0,
 206            62.0,48.8,45.5,44.2,52.0,51.5,49.8,48.8,57.2,59.0,53.2,56.0)
 207 npk <- data.frame(block = gl(6,4), N = factor(N), P = factor(P),
 208                   K = factor(K), yield = yield)
 209 npk.aov <- aov(yield ~ block + N*P*K, npk)
 210 op <- options(contrasts = c("contr.helmert", "contr.treatment"))
 211 npk.aovE <- aov(yield ~  N*P*K + Error(block), npk)
 212 options(op)
 213
 214 summary(npk.aov)
 215 print(xtable(npk.aov))
 216 print(xtable(anova(npk.aov)))
 217 print(xtable(summary(npk.aov)))
 218
 219 summary(npk.aovE)
 220 print(xtable(npk.aovE), type = "html")
 221 print(xtable(summary(npk.aovE)), type = "html")
 222
 223 ## Demonstrate lm
 224 ## Taken from help(lm) in R 1.1.1
 225 ## Annette Dobson (1990) "An Introduction to Generalized Linear Models".
 226 ## Page 9: Plant Weight Data.
 227 ctl <- c(4.17,5.58,5.18,6.11,4.50,4.61,5.17,4.53,5.33,5.14)
 228 trt <- c(4.81,4.17,4.41,3.59,5.87,3.83,6.03,4.89,4.32,4.69)
 229 group <- gl(2,10,20, labels = c("Ctl","Trt"))
 230 weight <- c(ctl, trt)
 231 lm.D9 <- lm(weight ~ group)
 232 print(xtable(lm.D9))
 233 print(xtable(anova(lm.D9)))
 234
 235 ## Demonstrate glm
 236 ## Taken from help(glm) in R 1.1.1
 237 ## Annette Dobson (1990) "An Introduction to Generalized Linear Models".
 238 ## Page 93: Randomized Controlled Trial :
 239 counts <- c(18,17,15,20,10,20,25,13,12)
 240 outcome <- gl(3,1,9)
 241 treatment <- gl(3,3)
 242 d.AD <- data.frame(treatment, outcome, counts)
 243 glm.D93 <- glm(counts ~ outcome + treatment, family = poisson())
 244 print(xtable(glm.D93, align = "r|llrc"))
 245 print(xtable(anova(glm.D93)), hline.after = c(1), size = "small")
 246
 247 ## Demonstration of additional formatC() arguments.
 248 print(fm1.table, format.args = list(big.mark = "'", decimal.mark = ","))
 249
 250 ## Demonstration of "short caption" support.
 251 fm1sc <- aov(tlimth ~ sex + ethnicty + grade, data = tli)
 252 fm1sc.table <- xtable(fm1sc,
 253   caption = c("ANOVA Model with Predictors Sex, Ethnicity, and Grade",
 254     "ANOVA: Sex, Ethnicity, Grade"))
 255 print(fm1sc.table)
 256
 257 ## Demonstration of longtable support.
 258 ## Remember to insert \usepackage{longtable} on your LaTeX preamble
 259 x <- matrix(rnorm(1000), ncol = 10)
 260 x.big <- xtable(x, label = 'tabbig',
 261                 caption = 'Example of longtable spanning several pages')
 262 print(x.big, tabular.environment = 'longtable', floating = FALSE)
 263 x <- x[1:30, ]
 264 x.small <- xtable(x, label = 'tabsmall', caption = 'regular table env')
 265 print(x.small)  # default, no longtable
 266
 267 ## Demonstration of sidewaystable support.
 268 ## Remember to insert \usepackage{rotating} on your LaTeX preamble
 269 print(x.small, floating.environment = 'sidewaystable')
 270
 271 if(require(stats, quietly = TRUE)) {
 272   ## Demonstrate prcomp
 273   ## Taken from help(prcomp) in mva package of R 1.1.1
 274   data(USArrests)
 275   pr1 <- prcomp(USArrests)
 276   print(xtable(pr1))
 277   print(xtable(summary(pr1)))
 278
 279 #  ## Demonstrate princomp
 280 #  ## Taken from help(princomp) in mva package of R 1.1.1
 281 #  pr2 <- princomp(USArrests)
 282 #  print(xtable(pr2))
 283 }
 284
 285 ## Demonstrate include.rownames, include.colnames,
 286 ## only.contents and add.to.row arguments
 287 set.seed(2345)
 288 res <- matrix(sample(0:9, size = 6*9, replace = TRUE), ncol = 6, nrow = 9)
 289 xres <- xtable(res)
 290 digits(xres) <- rep(0, 7)
 291 addtorow <- list()
 292 addtorow$pos <- list()
 293 addtorow$pos[[1]] <- c(0, 2)
 294 addtorow$pos[[2]] <- 4
 295 addtorow$command <- c('\\vspace{2mm} \n', '\\vspace{10mm} \n')
 296 print(xres, add.to.row = addtorow, include.rownames = FALSE,
 297       include.colnames = TRUE, only.contents = TRUE,
 298       hline.after = c(0, 0, 9, 9))
 299
 300 ## Demonstrate include.rownames, include.colnames,
 301 ## only.contents and add.to.row arguments in Rweave files
 302
 303 \dontrun{
 304  \begin{small}
 305  \setlongtables % For longtable version 3.x or less
 306  \begin{longtable}{
 307  <<results = tex, fig = FALSE>>=
 308  cat(paste(c('c', rep('cc', 34/2-1), 'c'), collapse = '@{\\hspace{2pt}}'))
 309  @
 310  }
 311  \hline
 312  \endhead
 313  \hline
 314  \endfoot
 315  <<results = tex, fig = FALSE>>=
 316  library(xtable)
 317  set.seed(2345)
 318  res <- matrix(sample(0:9, size = 34*90, replace = TRUE), ncol = 34, nrow = 90)
 319  xres <- xtable(res)
 320  digits(xres) <- rep(0, 35)
 321  addtorow <- list()
 322  addtorow$pos <- list()
 323  addtorow$pos[[1]] <- c(seq(4, 40, 5), seq(49, 85, 5))
 324  addtorow$pos[[2]] <- 45
 325  addtorow$command <- c('\\vspace{2mm} \n', '\\newpage \n')
 326  print(xres, add.to.row = addtorow, include.rownames = FALSE,
 327        include.colnames = FALSE, only.contents = TRUE, hline.after = NULL)
 328  @
 329  \end{longtable}
 330  \end{small}
 331 }
 332
 333 ## Demonstrate sanitization
 334 mat <- round(matrix(c(0.9, 0.89, 200, 0.045, 2.0), c(1, 5)), 4)
 335 rownames(mat) <- "$y_{t-1}$"
 336 colnames(mat) <- c("$R^2$", "$\\\bar{R}^2$", "F-stat", "S.E.E", "DW")
 337 print(xtable(mat), type = "latex", sanitize.text.function = function(x){x})
 338
 339 ## Demonstrate booktabs
 340 print(tli.table)
 341 print(tli.table, hline.after = c(-1,0))
 342 print(tli.table, hline.after = NULL)
 343 print(tli.table,
 344       add.to.row = list(pos = list(2), command = c("\\vspace{2mm} \n")))
 345
 346 print(tli.table, booktabs = TRUE)
 347 print(tli.table, booktabs = TRUE, hline.after = c(-1,0))
 348 print(tli.table, booktabs = TRUE, hline.after = NULL)
 349 print(tli.table, booktabs = TRUE,
 350   add.to.row = list(pos = list(2), command = c("\\vspace{2mm} \n")))
 351 print(tli.table, booktabs = TRUE, add.to.row = list(pos = list(2),
 352   command = c("youhou\n")), tabular.environment = "longtable")
 353
 354 \testonly{
 355   for(i in c("latex","html")) {
 356     outFileName <- paste("xtable.", ifelse(i=="latex", "tex", i), sep = "")
 357     print(tli.table, type = i, file = outFileName, append = FALSE)
 358     print(design.table, type = i, file = outFileName, append = TRUE)
 359     print(fm1.table, type = i, file = outFileName, append = TRUE)
 360     print(fm2.table, type = i, file = outFileName, append = TRUE)
 361     print(fm2.table, type = i, file = outFileName, append = TRUE,
 362           math.style.negative = TRUE)
 363     print(xtable(anova(fm2)), type = i, file = outFileName, append = TRUE)
 364     print(xtable(anova(fm2b, fm2)), type = i, file = outFileName, append = TRUE)
 365     print(fm3.table, type = i, file = outFileName, append = TRUE)
 366     print(xtable(anova(fm3)), type = i, file = outFileName, append = TRUE)
 367     print(xtable(npk.aov), type = i, file = outFileName, append = TRUE)
 368     print(xtable(anova(npk.aov)), type = i, file = outFileName, append = TRUE)
 369     print(xtable(summary(npk.aov)), type = i, file = outFileName, append = TRUE)
 370     print(xtable(npk.aovE), type = i, file = outFileName, append = TRUE)
 371     print(xtable(summary(npk.aovE)),
 372           type = i, file = outFileName, append = TRUE)
 373     if(i=="latex") cat("\\\clearpage\n", file = outFileName, append = TRUE)
 374     print(xtable(lm.D9),
 375           type = i, file = outFileName, append = TRUE, latex.environment = NULL)
 376     print(xtable(lm.D9),
 377           type = i, file = outFileName, append = TRUE, latex.environment = "")
 378     print(xtable(lm.D9),
 379           type = i, file = outFileName, append = TRUE,
 380           latex.environment = "center")
 381     print(xtable(anova(lm.D9)), type = i, file = outFileName, append = TRUE)
 382     print(xtable(glm.D93), type = i, file = outFileName, append = TRUE)
 383     print(xtable(anova(glm.D93, test = "Chisq")),
 384           type = i, file = outFileName, append = TRUE)
 385     print(xtable(glm.D93, align = "r|llrc"),
 386           include.rownames = FALSE, include.colnames = TRUE,
 387           type = i, file = outFileName, append = TRUE)
 388     print(xtable(glm.D93, align = "r||llrc"),
 389           include.rownames = TRUE, include.colnames = FALSE,
 390           type = i, file = outFileName, append = TRUE)
 391     print(xtable(glm.D93, align = "|r||llrc"),
 392           include.rownames = FALSE, include.colnames = FALSE,
 393           type = i, file = outFileName, append = TRUE)
 394     print(xtable(glm.D93, align = "|r||llrc|"),
 395           type = i, file = outFileName, append = TRUE)
 396     print(xtable(anova(glm.D93)),
 397           hline.after = c(1), size = "small",
 398           type = i, file = outFileName, append = TRUE)
 399     if(require(stats, quietly = TRUE)) {
 400       print(xtable(pr1), type = i, file = outFileName, append = TRUE)
 401       print(xtable(summary(pr1)), type = i, file = outFileName, append = TRUE)
 402       # print(xtable(pr2), type = i, file = outFileName, append = TRUE)
 403     }
 404     temp.table <- xtable(ts(cumsum(1+round(rnorm(100), 2)),
 405                             start = c(1954, 7), frequency = 12))
 406     caption(temp.table) <- "Time series example"
 407     print(temp.table, type = i, file = outFileName,
 408           append = TRUE, caption.placement = "top", table.placement = "h")
 409     print(temp.table, type = i, file = outFileName,
 410           append = TRUE, caption.placement = "bottom", table.placement = "htb")
 411   }
 412 }
 413
 414 }
 415 \keyword{file}