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