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