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