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