1\name{format.df} 2\alias{format.df} 3\title{ 4 Format a Data Frame or Matrix for LaTeX or HTML 5} 6\description{ 7 \code{format.df} does appropriate rounding and decimal alignment, and outputs 8 a character matrix containing the formatted data. If \code{x} is a 9 \code{data.frame}, then do each component separately. 10 If \code{x} is a matrix, but not a data.frame, make it a data.frame 11 with individual components for the columns. 12 If a component \code{x$x} is a matrix, then do all columns the same. 13} 14 15\usage{ 16format.df(x, digits, dec=NULL, rdec=NULL, cdec=NULL, 17 numeric.dollar=!dcolumn, na.blank=FALSE, na.dot=FALSE, 18 blank.dot=FALSE, col.just=NULL, cdot=FALSE, 19 dcolumn=FALSE, matrix.sep=' ', scientific=c(-4,4), 20 math.row.names=FALSE, math.col.names=FALSE, 21 double.slash=FALSE, format.Date="\%m/\%d/\%Y", 22 format.POSIXt="\%m/\%d/\%Y \%H:\%M:\%OS", \dots) 23} 24\arguments{ 25 \item{x}{ 26 a matrix (usually numeric) or data frame 27 } 28 \item{digits}{ 29 causes all values in the table to be formatted to \code{digits} significant 30 digits. \code{dec} is usually preferred. 31 } 32 \item{dec}{ 33 If \code{dec} is a scalar, all elements of the matrix will be rounded 34 to \code{dec} 35 decimal places to the right of the decimal. \code{dec} can also be a matrix 36 whose elements correspond to \code{x}, for customized rounding of each element. 37 A matrix \code{dec} must have number of columns equal to number of columns 38 of input \code{x}. 39 A scalar \code{dec} is expanded to a vector \code{cdec} with number of 40 items equal to number of columns of input \code{x}. 41 } 42 \item{rdec}{ 43 a vector specifying the number of decimal places to the right for each row 44 (\code{cdec} is more commonly used than \code{rdec}) 45 A vector \code{rdec} must have number of items equal to number of rows of input \code{x}. 46 \code{rdec} is expanded to matrix \code{dec}. 47 } 48 \item{cdec}{ 49 a vector specifying the number of decimal places for each column. 50 The vector must have number of items equal to number of columns or components 51 of input x. 52 } 53 \item{cdot}{ 54 Set to \code{TRUE} to use centered dots rather than ordinary periods in numbers. 55 The output uses a syntax appropriate for \code{latex}. 56 } 57 \item{na.blank}{ 58 Set to \code{TRUE} to use blanks rather than \code{NA} for missing values. 59 This usually looks better in \code{latex}. 60 } 61 \item{dcolumn}{ 62 Set to \code{TRUE} to use David Carlisle's dcolumn style for 63 decimal alignment in \code{latex}. 64 Default is \code{FALSE}. You will probably want to 65 use \code{dcolumn} if you use \code{rdec}, as a column may then contain varying 66 number of places to the right of the decimal. \code{dcolumn} can line up 67 all such numbers on the decimal point, with integer values right 68 justified at the decimal point location of numbers that actually 69 contain decimal places. When you use \code{dcolumn = TRUE}, 70 \code{numeric.dollar} is set by default to \code{FALSE}. When you 71 use \code{dcolumn = TRUE}, the 72 object attribute \code{"style"} set to \samp{dcolumn} as the \code{latex} \preformatted{\\usepackage} 73 must reference \preformatted{[dcolumn]}. 74 The three files \file{dcolumn.sty}, \file{newarray.sty}, and 75 \file{array.sty} will 76 need to be in a directory in your \env{TEXINPUTS} path. 77 When you use \code{dcolumn=TRUE}, \code{numeric.dollar} should be set to \code{FALSE}. 78 } 79 \item{numeric.dollar}{ 80 logical, default \code{!dcolumn}. Set to \code{TRUE} to place dollar 81 signs around numeric values when \code{dcolumn = FALSE}. This 82 assures that \code{latex} will use minus signs rather than hyphens to indicate 83 negative numbers. Set to \code{FALSE} when \code{dcolumn = TRUE}, as 84 \code{dcolumn.sty} automatically uses minus signs. 85 } 86 \item{math.row.names}{ 87 logical, set true to place dollar signs around the row names. 88 } 89 \item{math.col.names}{ 90 logical, set true to place dollar signs around the column names. 91 } 92 \item{na.dot}{ 93 Set to \code{TRUE} to use periods rather than \code{NA} for missing 94 numeric values. 95 This works with the \acronym{SAS} convention that periods indicate missing values. 96 } 97 \item{blank.dot}{ 98 Set to \code{TRUE} to use periods rather than blanks for missing character values. 99 This works with the \acronym{SAS} convention that periods indicate missing values. 100 } 101 \item{col.just}{ 102 Input vector \code{col.just} must have number of columns equal to 103 number of columns of the output matrix. When \code{NULL}, the 104 default, the \code{col.just} attribute of the result is set to 105 \samp{l} for character columns and to \samp{r} for numeric 106 columns. The user can override the default by an argument vector 107 whose length is equal to the number of columns of the result matrix. 108 When \code{format.df} is called by \code{latex.default}, the 109 \code{col.just} is used as the \code{cols} argument to the 110 \preformatted{\\tabular} environment and the letters \samp{l}, \samp{r}, 111 and \samp{c} are valid values. When \code{format.df} is called by 112 \acronym{SAS}, the \code{col.just} is used to determine whether a 113 \samp{\$} is needed on the \samp{input} line of the \file{sysin} file, 114 and the letters \samp{l} and \samp{r} are valid values. 115 } 116 \item{matrix.sep}{ 117 When \code{x} is a data frame containing a matrix, so that new column names 118 are constructed from the name of the matrix object and the names of 119 the individual columns of the matrix, \code{matrix.sep} specifies the 120 character to use to separate object names from individual column 121 names. 122 } 123 \item{scientific}{ 124 specifies ranges of exponents (or a logical vector) specifying values 125 not to convert to scientific notation. See \code{format.default} for details. 126 } 127 \item{double.slash}{ 128 should escaping backslashes be themselves escaped. 129 } 130 \item{format.Date}{ 131 String used to format objects of the Date class. 132 } 133 \item{format.POSIXt}{ 134 String used to format objects of the POSIXt class. 135 } 136 \item{\dots}{ 137 other arguments are accepted and ignored. For \code{latexVerbatim} these 138 arguments are passed to the \code{print} function. 139 } 140} 141\value{ 142 a character matrix with character images of properly rounded \code{x}. 143 Matrix components of input \code{x} are now just sets of columns of 144 character matrix. 145 Object attribute\code{"col.just"} repeats the value of the argument \code{col.just} when provided, 146 otherwise, it includes the recommended justification for columns of output. 147 See the discussion of the argument \code{col.just}. 148 The default justification is \samp{l} for characters and factors, 149 \samp{r} for numeric. 150 When \code{dcolumn==TRUE}, numerics will have \samp{.} as the justification character. 151} 152 153\author{ 154 Frank E. Harrell, Jr., 155 \cr 156 Department of Biostatistics, 157 \cr 158 Vanderbilt University, 159 \cr 160 \email{f.harrell@vanderbilt.edu} 161 162 163 Richard M. Heiberger, 164 \cr 165 Department of Statistics, 166 \cr 167 Temple University, Philadelphia, PA. 168 \cr 169 \email{rmh@astro.ocis.temple.edu} 170 171 172} 173\seealso{ 174 \code{\link{latex}} 175} 176\examples{ 177\dontrun{ 178x <- data.frame(a=1:2, b=3:4) 179x$m <- matrix(5:8,nrow=2) 180names(x) 181dim(x) 182x 183format.df(x) 184dim(format.df(x)) 185} 186} 187\keyword{utilities} 188\keyword{interface} 189\keyword{methods} 190\keyword{file} 191\keyword{character} 192\keyword{manip} 193