1% File src/library/utils/man/write.table.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2014 R Core Team 4% Distributed under GPL 2 or later 5 6\name{write.table} 7\alias{write.table} 8\alias{write.csv} 9\alias{write.csv2} 10\title{Data Output} 11\description{ 12 \code{write.table} prints its required argument \code{x} (after 13 converting it to a data frame if it is not one nor a matrix) to 14 a file or \link{connection}. 15} 16\usage{ 17write.table(x, file = "", append = FALSE, quote = TRUE, sep = " ", 18 eol = "\n", na = "NA", dec = ".", row.names = TRUE, 19 col.names = TRUE, qmethod = c("escape", "double"), 20 fileEncoding = "") 21 22write.csv(\dots) 23write.csv2(\dots) 24} 25\arguments{ 26 \item{x}{the object to be written, preferably a matrix or data frame. 27 If not, it is attempted to coerce \code{x} to a data frame.} 28 \item{file}{either a character string naming a file or a \link{connection} 29 open for writing. \code{""} indicates output to the console.} 30 \item{append}{logical. Only relevant if \code{file} is a character 31 string. If \code{TRUE}, the output is appended to the 32 file. If \code{FALSE}, any existing file of the name is destroyed.} 33 \item{quote}{a logical value (\code{TRUE} or \code{FALSE}) or a 34 numeric vector. If \code{TRUE}, any character or factor columns 35 will be surrounded by double quotes. If a numeric vector, its 36 elements are taken as the indices of columns to quote. In both 37 cases, row and column names are quoted if they are written. If 38 \code{FALSE}, nothing is quoted.} 39 \item{sep}{the field separator string. Values within each row of 40 \code{x} are separated by this string.} 41 \item{eol}{the character(s) to print at the end of each line (row). 42 For example, \code{eol = "\r\n"} will produce Windows' line endings on 43 a Unix-alike OS, and \code{eol = "\r"} will produce files as expected by 44 Excel:mac 2004.} 45 \item{na}{the string to use for missing values in the data.} 46 \item{dec}{the string to use for decimal points in numeric or complex 47 columns: must be a single character.} 48 \item{row.names}{either a logical value indicating whether the row 49 names of \code{x} are to be written along with \code{x}, or a 50 character vector of row names to be written.} 51 \item{col.names}{either a logical value indicating whether the column 52 names of \code{x} are to be written along with \code{x}, or a 53 character vector of column names to be written. See the section on 54 \sQuote{CSV files} for the meaning of \code{col.names = NA}.} 55 \item{qmethod}{a character string specifying how to deal with embedded 56 double quote characters when quoting strings. Must be one of 57 \code{"escape"} (default for \code{write.table}), in which case the 58 quote character is escaped in C style by a backslash, or 59 \code{"double"} (default for \code{write.csv} and 60 \code{write.csv2}), in which case it is doubled. You can specify 61 just the initial letter.} 62 \item{fileEncoding}{character string: if non-empty declares the 63 encoding to be used on a file (not a connection) so the character data can 64 be re-encoded as they are written. See \code{\link{file}}.} 65 66 \item{\dots}{arguments to \code{write.table}: \code{append}, 67 \code{col.names}, \code{sep}, \code{dec} and \code{qmethod} 68 cannot be altered. 69 } 70} 71\details{ 72 If the table has no columns the rownames will be written only if 73 \code{row.names = TRUE}, and \emph{vice versa}. 74 75 Real and complex numbers are written to the maximal possible precision. 76 77 If a data frame has matrix-like columns these will be converted to 78 multiple columns in the result (\emph{via} \code{\link{as.matrix}}) 79 and so a character \code{col.names} or a numeric \code{quote} should 80 refer to the columns in the result, not the input. Such matrix-like 81 columns are unquoted by default. 82 83 Any columns in a data frame which are lists or have a class 84 (e.g., dates) will be converted by the appropriate \code{as.character} 85 method: such columns are unquoted by default. On the other hand, 86 any class information for a matrix is discarded and non-atomic 87 (e.g., list) matrices are coerced to character. 88 89 Only columns which have been converted to character will be quoted if 90 specified by \code{quote}. 91 92 The \code{dec} argument only applies to columns that are not subject 93 to conversion to character because they have a class or are part of a 94 matrix-like column (or matrix), in particular to columns protected by 95 \code{\link{I}()}. Use \code{\link{options}("OutDec")} to control 96 such conversions. 97 98 In almost all cases the conversion of numeric quantities is governed 99 by the option \code{"scipen"} (see \code{\link{options}}), but with 100 the internal equivalent of \code{digits = 15}. For finer control, use 101 \code{\link{format}} to make a character matrix/data frame, and call 102 \code{write.table} on that. 103 104 These functions check for a user interrupt every 1000 lines of output. 105 106 If \code{file} is a non-open connection, an attempt is made to open it 107 and then close it after use. 108 109 To write a Unix-style file on Windows, use a binary connection 110 e.g.\sspace{}\code{file = file("filename", "wb")}. 111} 112\section{CSV files}{ 113 By default there is no column name for a column of row names. If 114 \code{col.names = NA} and \code{row.names = TRUE} a blank column name 115 is added, which is the convention used for CSV files to be read by 116 spreadsheets. Note that such CSV files can be read in \R by 117\preformatted{ read.csv(file = "<filename>", row.names = 1)} 118 119 \code{write.csv} and \code{write.csv2} provide convenience wrappers 120 for writing CSV files. They set \code{sep} and \code{dec} (see 121 below), \code{qmethod = "double"}, and \code{col.names} to \code{NA} 122 if \code{row.names = TRUE} (the default) and to \code{TRUE} otherwise. 123 124 \code{write.csv} uses \code{"."} for the decimal point and a comma for 125 the separator. 126 127 \code{write.csv2} uses a comma for the decimal point and a semicolon for 128 the separator, the Excel convention for CSV files in some Western 129 European locales. 130 131 These wrappers are deliberately inflexible: they are designed to 132 ensure that the correct conventions are used to write a valid file. 133 Attempts to change \code{append}, \code{col.names}, \code{sep}, 134 \code{dec} or \code{qmethod} are ignored, with a warning. 135 136 CSV files do not record an encoding, and this causes problems if they 137 are not ASCII for many other applications. Windows Excel 2007/10 will 138 open files (e.g., by the file association mechanism) correctly if they 139 are ASCII or UTF-16 (use \code{fileEncoding = "UTF-16LE"}) or perhaps 140 in the current Windows codepage (e.g., \code{"CP1252"}), but the 141 \sQuote{Text Import Wizard} (from the \sQuote{Data} tab) allows far 142 more choice of encodings. Excel:mac 2004/8 can \emph{import} only 143 \sQuote{Macintosh} (which seems to mean Mac Roman), \sQuote{Windows} 144 (perhaps Latin-1) and \sQuote{PC-8} files. OpenOffice 3.x asks for 145 the character set when opening the file. 146 147 There is an IETF RFC4180 (\url{https://tools.ietf.org/html/rfc4180}) 148 for CSV files, which mandates comma as the separator and CRLF line 149 endings. \code{write.csv} writes compliant files on Windows: use 150 \code{eol = "\r\n"} on other platforms. 151} 152\note{ 153 \code{write.table} can be slow for data frames with large numbers 154 (hundreds or more) of columns: this is inevitable as each column could 155 be of a different class and so must be handled separately. If they 156 are all of the same class, consider using a matrix instead. 157} 158 159\seealso{ 160 The \sQuote{R Data Import/Export} manual. 161 162 \code{\link{read.table}}, \code{\link{write}}. 163 164 \code{\link[MASS]{write.matrix}} in package \CRANpkg{MASS}. 165} 166 167\examples{ 168\dontrun{ 169## To write a CSV file for input to Excel one might use 170x <- data.frame(a = I("a \" quote"), b = pi) 171write.table(x, file = "foo.csv", sep = ",", col.names = NA, 172 qmethod = "double") 173## and to read this file back into R one needs 174read.table("foo.csv", header = TRUE, sep = ",", row.names = 1) 175## NB: you do need to specify a separator if qmethod = "double". 176 177### Alternatively 178write.csv(x, file = "foo.csv") 179read.csv("foo.csv", row.names = 1) 180## or without row names 181write.csv(x, file = "foo.csv", row.names = FALSE) 182read.csv("foo.csv") 183 184## To write a file in Mac Roman for simple use in Mac Excel 2004/8 185write.csv(x, file = "foo.csv", fileEncoding = "macroman") 186## or for Windows Excel 2007/10 187write.csv(x, file = "foo.csv", fileEncoding = "UTF-16LE") 188}} 189\keyword{print} 190\keyword{file} 191