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 additional formatC() arguments.
 197 print(fm1.table, format.args=list(big.mark = "'", decimal.mark = ","))
 198
 199 ## Demonstration of longtable support.
 200 ## Remember to insert \usepackage{longtable} on your LaTeX preamble
 201 x <- matrix(rnorm(1000), ncol = 10)
 202 x.big <- xtable(x,label='tabbig',caption='Example of longtable spanning several pages')
 203 print(x.big,tabular.environment='longtable',floating=FALSE)
 204 x <- x[1:30,]
 205 x.small <- xtable(x,label='tabsmall',caption='regular table env')
 206 print(x.small)  # default, no longtable
 207
 208 ## Demonstration of sidewaystable support.
 209 ## Remember to insert \usepackage{rotating} on your LaTeX preamble
 210 print(x.small,floating.environment='sidewaystable')
 211
 212 if(require(stats,quietly=TRUE)) {
 213   ## Demonstrate prcomp
 214   ## Taken from help(prcomp) in mva package of R 1.1.1
 215   data(USArrests)
 216   pr1 <- prcomp(USArrests)
 217   print(xtable(pr1))
 218   print(xtable(summary(pr1)))
 219
 220 #  ## Demonstrate princomp
 221 #  ## Taken from help(princomp) in mva package of R 1.1.1
 222 #  pr2 <- princomp(USArrests)
 223 #  print(xtable(pr2))
 224 }
 225
 226 ## Demonstrate include.rownames, include.colnames,
 227 ## only.contents and add.to.row arguments
 228 set.seed(2345)
 229 res <- matrix(sample(0:9, size=6*9, replace=TRUE), ncol=6, nrow=9)
 230 xres <- xtable(res)
 231 digits(xres) <- rep(0, 7)
 232 addtorow <- list()
 233 addtorow$pos <- list()
 234 addtorow$pos[[1]] <- c(0, 2)
 235 addtorow$pos[[2]] <- 4
 236 addtorow$command <- c('\\vspace{2mm} \n', '\\vspace{10mm} \n')
 237 print(xres, add.to.row=addtorow, include.rownames=FALSE, include.colnames=TRUE,
 238   only.contents=TRUE, hline.after=c(0, 0, 9, 9))
 239
 240 ## Demostrate include.rownames, include.colnames,
 241 ## only.contents and add.to.row arguments in Rweave files
 242
 243 \dontrun{
 244  \begin{small}
 245  \setlongtables % For longtable version 3.x or less
 246  \begin{longtable}{
 247  <<results=tex,fig=FALSE>>=
 248  cat(paste(c('c', rep('cc', 34/2-1), 'c'), collapse='@{\\hspace{2pt}}'))
 249  @
 250  }
 251  \hline
 252  \endhead
 253  \hline
 254  \endfoot
 255  <<results=tex,fig=FALSE>>=
 256  library(xtable)
 257  set.seed(2345)
 258  res <- matrix(sample(0:9, size=34*90, replace=TRUE), ncol=34, nrow=90)
 259  xres <- xtable(res)
 260  digits(xres) <- rep(0, 35)
 261  addtorow <- list()
 262  addtorow$pos <- list()
 263  addtorow$pos[[1]] <- c(seq(4, 40, 5), seq(49, 85, 5))
 264  addtorow$pos[[2]] <- 45
 265  addtorow$command <- c('\\vspace{2mm} \n', '\\newpage \n')
 266  print(xres, add.to.row=addtorow, include.rownames=FALSE, include.colnames=FALSE,
 267    only.contents=TRUE, hline.after=NULL)
 268  @
 269  \end{longtable}
 270  \end{small}
 271 }
 272
 273 ## Demonstrate sanitization
 274 mat <- round(matrix(c(0.9, 0.89, 200, 0.045, 2.0), c(1, 5)), 4)
 275 rownames(mat) <- "$y_{t-1}$"
 276 colnames(mat) <- c("$R^2$", "$\\\bar{R}^2$", "F-stat", "S.E.E", "DW")
 277 print(xtable(mat), type="latex", sanitize.text.function = function(x){x})
 278
 279 \testonly{
 280   for(i in c("latex","html")) {
 281     outFileName <- paste("xtable.",ifelse(i=="latex","tex",i),sep="")
 282     print(tli.table,type=i,file=outFileName,append=FALSE)
 283     print(design.table,type=i,file=outFileName,append=TRUE)
 284     print(fm1.table,type=i,file=outFileName,append=TRUE)
 285     print(fm2.table,type=i,file=outFileName,append=TRUE)
 286     print(fm2.table,type=i,file=outFileName,append=TRUE,math.style.negative=TRUE)
 287     print(xtable(anova(fm2)),type=i,file=outFileName,append=TRUE)
 288     print(xtable(anova(fm2b,fm2)),type=i,file=outFileName,append=TRUE)
 289     print(fm3.table,type=i,file=outFileName,append=TRUE)
 290     print(xtable(anova(fm3)),type=i,file=outFileName,append=TRUE)
 291     print(xtable(npk.aov),type=i,file=outFileName,append=TRUE)
 292     print(xtable(anova(npk.aov)),type=i,file=outFileName,append=TRUE)
 293     print(xtable(summary(npk.aov)),type=i,file=outFileName,append=TRUE)
 294     print(xtable(npk.aovE),type=i,file=outFileName,append=TRUE)
 295     print(xtable(summary(npk.aovE)),type=i,file=outFileName,append=TRUE)
 296     if(i=="latex") cat("\\\clearpage\n",file=outFileName,append=TRUE)
 297     print(xtable(lm.D9),type=i,file=outFileName,append=TRUE,latex.environment=NULL)
 298     print(xtable(lm.D9),type=i,file=outFileName,append=TRUE,latex.environment="")
 299     print(xtable(lm.D9),type=i,file=outFileName,append=TRUE,latex.environment="center")
 300     print(xtable(anova(lm.D9)),type=i,file=outFileName,append=TRUE)
 301     print(xtable(glm.D93),type=i,file=outFileName,append=TRUE)
 302     print(xtable(anova(glm.D93,test="Chisq")),type=i,file=outFileName,append=TRUE)
 303     print(xtable(glm.D93,align="r|llrc"),include.rownames=FALSE,include.colnames=TRUE,
 304       type=i,file=outFileName,append=TRUE)
 305     print(xtable(glm.D93,align="r||llrc"),include.rownames=TRUE,include.colnames=FALSE,
 306       type=i,file=outFileName,append=TRUE)
 307     print(xtable(glm.D93,align="|r||llrc"),include.rownames=FALSE,include.colnames=FALSE,
 308       type=i,file=outFileName,append=TRUE)
 309     print(xtable(glm.D93,align="|r||llrc|"),type=i,file=outFileName,append=TRUE)
 310     print(xtable(anova(glm.D93)),hline.after=c(1),size="small",type=i,file=outFileName, append=TRUE)
 311     if(require(stats,quietly=TRUE)) {
 312       print(xtable(pr1),type=i,file=outFileName,append=TRUE)
 313       print(xtable(summary(pr1)),type=i,file=outFileName,append=TRUE)
 314       # print(xtable(pr2),type=i,file=outFileName,append=TRUE)
 315     }
 316     temp.table <- xtable(ts(cumsum(1+round(rnorm(100), 2)), start = c(1954, 7), frequency=12))
 317     caption(temp.table) <- "Time series example"
 318     print(temp.table,type=i,file=outFileName,append=TRUE,caption.placement="top",
 319       table.placement="h")
 320     print(temp.table,type=i,file=outFileName,append=TRUE,caption.placement="bottom",
 321       table.placement="htb")
 322   }
 323 }
 324
 325 }
 326 \keyword{file}