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