pkg/man/print.xtable.Rd

   1 \name{print.xtable}\r
   2 \alias{print.xtable}\r
   3 \title{Print Export Tables}\r
   4 \description{\r
   5   Function returning and displaying or writing to disk the LaTeX or HTML\r
   6   code associated with the supplied object of class \code{xtable}.\r
   7 }\r
   8 \usage{\r
   9 \method{print}{xtable}(x, \r
  10   type = getOption("xtable.type", "latex"),\r
  11   file = getOption("xtable.file", ""),\r
  12   append = getOption("xtable.append", FALSE),\r
  13   floating = getOption("xtable.floating", TRUE),\r
  14   floating.environment = getOption("xtable.floating.environment", "table"),\r
  15   table.placement = getOption("xtable.table.placement", "ht"),\r
  16   caption.placement = getOption("xtable.caption.placement", "bottom"),\r
  17   latex.environments = getOption("xtable.latex.environments", c("center")),\r
  18   tabular.environment = getOption("xtable.tabular.environment", "tabular"),\r
  19   size = getOption("xtable.size", NULL),\r
  20   hline.after = getOption("xtable.hline.after", c(-1,0,nrow(x))),\r
  21   NA.string = getOption("xtable.NA.string", ""),\r
  22   include.rownames = getOption("xtable.include.rownames", TRUE),\r
  23   include.colnames = getOption("xtable.include.colnames", TRUE),\r
  24   only.contents = getOption("xtable.only.contents", FALSE),\r
  25   add.to.row = getOption("xtable.add.to.row", NULL),\r
  26   sanitize.text.function = getOption("xtable.sanitize.text.function", NULL),\r
  27   sanitize.rownames.function = getOption("xtable.sanitize.rownames.function", \r
  28                                          sanitize.text.function),\r
  29   sanitize.colnames.function = getOption("xtable.sanitize.colnames.function", \r
  30                                          sanitize.text.function),\r
  31   math.style.negative = getOption("xtable.math.style.negative", FALSE),\r
  32   html.table.attributes = getOption("xtable.html.table.attributes",\r
  33                                     "border=1"),\r
  34   print.results = getOption("xtable.print.results", TRUE),\r
  35   format.args = getOption("xtable.format.args", NULL),\r
  36   rotate.rownames = getOption("xtable.rotate.rownames", FALSE),\r
  37   rotate.colnames = getOption("xtable.rotate.colnames", FALSE),\r
  38   booktabs = getOption("xtable.booktabs", FALSE),\r
  39   scalebox = getOption("xtable.scalebox", NULL),\r
  40   width = getOption("xtable.width", NULL),\r
  41   timestamp = date(),\r
  42   ...)}\r
  43 \arguments{\r
  44   \item{x}{An object of class \code{"xtable"}.}\r
  45   \item{type}{Type of table to produce.  Possible values for \code{type}\r
  46     are \code{"latex"} or \code{"html"}.\r
  47     Default value is \code{"latex"}.}\r
  48   \item{file}{Name of file where the resulting code should be saved.  If\r
  49     \code{file=""}, output is displayed on screen.  Note that the\r
  50     function also (invisibly) returns a character vector of the results\r
  51     (which can be helpful for post-processing).\r
  52     Default value is \code{""}.}\r
  53   \item{append}{If \code{TRUE} and \code{file!=""}, code will be\r
  54     appended to \code{file} instead of overwriting \code{file}.\r
  55     Default value is \code{FALSE}.}\r
  56   \item{floating}{If \code{TRUE} and \code{type="latex"}, the resulting\r
  57     table will be a floating table (using, for example,\r
  58     \code{\\begin\{table\}} and \code{\\end\{table\}}).  See\r
  59     \code{floating.environment} below.\r
  60     Default value is \code{TRUE}. }\r
  61   \item{floating.environment}{If \code{floating=TRUE} and\r
  62     \code{type="latex"}, the resulting table uses the specified floating\r
  63     environment. Possible values are \code{"table"}, \code{"table*"}, or\r
  64     \code{"sidewaystable"} (defined in the LaTeX package\r
  65     'rotating').\r
  66     Default value is \code{"table"}.}\r
  67   \item{table.placement}{If \code{floating=TRUE} and\r
  68     \code{type="latex"}, the floating table will have placement given by\r
  69     \code{table.placement} where \code{table.placement} must be\r
  70     \code{NULL} or contain only elements of\r
  71     \{"h","t","b","p","!","H"\}.\r
  72     Default value is \code{"ht"}.}\r
  73   \item{caption.placement}{The caption will be have placed at the bottom\r
  74     of the table if \code{caption.placement} is \code{"bottom"} and at\r
  75     the top of the table if it equals \code{"top"}.\r
  76     Default value is \code{"bottom"}.}\r
  77   \item{latex.environments}{If \code{floating=TRUE} and\r
  78     \code{type="latex"}, the specificed latex environments (provided as\r
  79     a character vector) will enclose the tabular environment.\r
  80     Default value is \code{"center"}. }\r
  81   \item{tabular.environment}{When \code{type="latex"}, the tabular\r
  82     environment that will be used.\r
  83     Defaults to \code{"tabular"}.\r
  84     When working with tables that extend more than one page, using\r
  85     \code{tabular.environment="longtable"} and the LaTeX package\r
  86     \code{"longtable"} (see Fairbairns, 2005) allows one to typeset them\r
  87     uniformly. Note that \code{"floating"} should be set to\r
  88     \code{"FALSE"} when using the \code{"longtable"} environment.}\r
  89   \item{size}{An arbitrary character vector intended to be used to set\r
  90     the font size in a LaTeX table.  The supplied value (if not\r
  91     \code{NULL}) is inserted just before the tabular environment\r
  92     starts.\r
  93     Default value is \code{NULL}. }\r
  94   \item{hline.after}{When \code{type="latex"}, a vector of numbers\r
  95     between -1 and \code{"nrow(x)"}, inclusive, indicating the rows\r
  96     after which a horizontal line should appear.  If \code{NULL} is used\r
  97     no lines are produced.\r
  98     Default value is \code{c(-1,0,nrow(x))} which means draw a line\r
  99     before and after the columns names and at the end of the\r
 100     table. Repeated values are allowed.}\r
 101   \item{NA.string}{String to be used for missing values in table\r
 102     entries.\r
 103     Default value is \code{""}.}\r
 104   \item{include.rownames}{logical. If \code{TRUE} the rows names is\r
 105     printed.\r
 106     Default value is \code{TRUE}.}\r
 107   \item{include.colnames}{logical. If \code{TRUE} the columns names is\r
 108     printed.\r
 109     Default value is \code{TRUE}.}\r
 110   \item{only.contents}{logical. If \code{TRUE} only the rows of the\r
 111     table is printed.\r
 112     Default value is \code{FALSE}. }\r
 113   \item{add.to.row}{a list of two components. The first component (which\r
 114     should be called 'pos') is a list contains the position of rows on\r
 115     which extra commands should be added at the end, The second\r
 116     component (which should be called 'command') is a character vector\r
 117     of the same length of the first component which contains the command\r
 118     that should be added at the end of the specified rows.\r
 119     Default value is \code{NULL}, i.e. do not add commands.}\r
 120   \item{sanitize.text.function}{All non-numeric enteries (except row and\r
 121     column names) are sanitised in an attempt to remove characters which\r
 122     have special meaning for the output format. If\r
 123     \code{sanitize.text.function} is not NULL (the default), it should\r
 124     be a function taking a character vector and returning one, and will\r
 125     be used for the sanitization instead of the default internal\r
 126     function.}\r
 127   \item{sanitize.rownames.function}{Like the\r
 128     \code{sanitize.text.function}, but applicable to row names.\r
 129     The default uses the \code{sanitize.text.function}. }\r
 130   \item{sanitize.colnames.function}{Like the\r
 131     \code{sanitize.text.function}, but applicable to column names.\r
 132     The default uses the \code{sanitize.text.function}. }\r
 133   \item{math.style.negative}{In a LaTeX table, if \code{TRUE}, then use\r
 134     $-$ for the negative sign (as was the behavior prior to version 1.5-3).\r
 135     Default value is \code{FALSE}.}\r
 136   \item{html.table.attributes}{In an HTML table, attributes associated\r
 137     with the \code{<TABLE>}tag.\r
 138     Default value is \code{border=1}.}\r
 139   \item{print.results}{If \code{TRUE}, the generated table is printed to\r
 140     standard output.  Set this to \code{FALSE} if you will just be using\r
 141     the character vector that is returned invisibly.}\r
 142   \item{format.args}{List of arguments for the \code{formatC} function.\r
 143     For example, standard German number separators can be specified as\r
 144     \code{format.args=list(big.mark = "'", decimal.mark = ","))}. }\r
 145   \item{rotate.rownames}{If \code{TRUE}, the row names are displayed\r
 146     vertically in LaTeX. }\r
 147   \item{rotate.colnames}{If \code{TRUE}, the column names are displayed\r
 148     vertically in LaTeX. }\r
 149   \item{booktabs}{If \code{TRUE}, the \code{toprule}, \code{midrule} and\r
 150     \code{bottomrule} tags from the LaTex "booktabs" package are used\r
 151     rather than \code{hline} for the horizontal line tags. }\r
 152   \item{scalebox}{If not \code{NULL}, a \code{scalebox} clause will be\r
 153     added around the tabular environment with the specified value used\r
 154     as the scaling factor. }\r
 155   \item{width}{If not \code{NULL}, the specified value is included in\r
 156     parenthesis between the tabular environment \code{begin} tag and the\r
 157     alignment specification.  This allows specification of the table\r
 158     width when using tabular environments such as \code{tabular*} and\r
 159     \code{tabularx}.  Note that table width specification is not\r
 160     supported with the \code{tabular} or \code{longtable} environments. }\r
 161   \item{timestamp}{Timestamp to include in LaTeX comment.  Set this\r
 162     to \code{NULL} to exclude the timestamp.}  \r
 163   \item{...}{Additional arguments.  (Currently ignored.)}\r
 164 }\r
 165 \details{\r
 166   This function displays or writes to disk the code to produce a table\r
 167   associated with an object \code{x} of class \code{"xtable"}. \r
 168   The resulting code is either a LaTeX or HTML table, depending on the\r
 169   value of \code{type}.  The function also (invisibly) returns a\r
 170   character vector of the results (which can be helpful for\r
 171   post-processing).\r
 172 \r
 173   Since version 1.4 the non default behavior of \code{hline.after} is\r
 174   changed. To obtain the same results as the previous versions add to\r
 175   the \code{hline.after} vector the vector \code{c(-1, 0, nrow(x))}\r
 176   where \code{nrow(x)} is the numbers of rows of the object. \r
 177 \r
 178   From version 1.4-3, all non-numeric columns are sanitized, and all\r
 179   LaTeX special characters are sanitised for LaTeX output.  See Section\r
 180   3 of the \code{xtableGallery} vignette for an example of customising\r
 181   the sanitization. From version 1.4-4, the sanitization also applies to\r
 182   column names.  To remove any text sanitization, specify\r
 183   \code{sanitize.text.function=function(x){x}}.  \r
 184   \r
 185   From version 1.6-1 the default values for the arguments other than\r
 186   \code{x} are obtainined using \code{getOption()}.  Hence the user can\r
 187   set the values once with \code{options()} rather than setting them in\r
 188   every call to \code{print.xtable()}. \r
 189 }\r
 190 \author{\r
 191   David Dahl \email{dahl@stat.tamu.edu} with contributions and\r
 192   suggestions from many others (see source code).\r
 193 }\r
 194 \references{\r
 195   Fairbairns, Robin (2005) \emph{Tables longer than a single page} The\r
 196   UK List of TeX Frequently Asked Questions on the\r
 197   Web. \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=longtab}\r
 198 }\r
 199 \seealso{\r
 200   \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}}, \r
 201   \code{\link{align}}, \code{\link{digits}}, \code{\link{display}},\r
 202   \code{\link{formatC}} \r
 203 }\r
 204 \r
 205 \keyword{print}\r