write.table              package:utils              R Documentation

Data Output

Description:

     'write.table' prints its required argument 'x' (after converting
     it to a data frame if it is not one nor a matrix) to a file or
     connection.

Usage:

     write.table(x, file = "", append = FALSE, quote = TRUE, sep = " ",
                 eol = "\n", na = "NA", dec = ".", row.names = TRUE,
                 col.names = TRUE, qmethod = c("escape", "double"))

     write.csv(...)
     write.csv2(...)

Arguments:

       x: the object to be written, preferably a matrix or data frame.
          If not, it is attempted to coerce 'x' to a data frame.

    file: either a character string naming a file or a connection open
          for writing.  '""' indicates output to the console.

  append: logical. Only relevant if 'file' is a character string.  If
          'TRUE', the output is appended to the file.  If 'FALSE', any
          existing file of the name is destroyed.

   quote: a logical value ('TRUE' or 'FALSE') or a numeric vector.  If
          'TRUE', any character or factor columns will be surrounded by
          double quotes.  If a numeric vector, its elements are taken
          as the indices of columns to quote.  In both cases, row and
          column names are quoted if they are written.  If 'FALSE',
          nothing is quoted.

     sep: the field separator string.  Values within each row of 'x'
          are separated by this string.

     eol: the character(s) to print at the end of each line (row). For
          example, 'eol="\r\n"' will produce Windows' line endings on a
          Unix-alike OS, and 'eol="\r"' will produce files as expected
          by MacOS Excel 2004.

      na: the string to use for missing values in the data.

     dec: the string to use for decimal points in numeric or complex
          columns: must be a single character.

row.names: either a logical value indicating whether the row names of
          'x' are to be written along with 'x', or a character vector
          of row names to be written.

col.names: either a logical value indicating whether the column names
          of 'x' are to be written along with 'x', or a character
          vector of column names to be written.  See the section on
          'CSV files' for the meaning of 'col.names = NA'.

 qmethod: a character string specifying how to deal with embedded
          double quote characters when quoting strings.  Must be one of
          '"escape"' (default), in which case the quote character is
          escaped in C style by a backslash, or '"double"', in which
          case it is doubled.  You can specify just the initial letter.

     ...: arguments to 'write.table': 'col.names', 'sep', 'dec' and
          'qmethod' cannot be altered. 

Details:

     If the table has no columns the rownames will be written only if
     'row.names=TRUE', and _vice versa_.

     Real and complex numbers are written to the maximal possible
     precision.

     If a data frame has matrix-like columns these will be converted to
     multiple columns in the result (_via_ 'as.matrix') and so a
     character 'col.names' or a numeric 'quote' should refer to the
     columns in the result, not the input.  Such matrix-like columns
     are unquoted by default.

     Any columns in a data frame which are lists or have a class (e.g.
     dates) will be converted by the appropriate 'as.character' method:
     such columns are unquoted by default.  On the other hand, any
     class information for a matrix is discarded and non-atomic (e.g.
     list) matrices are coerced to character.

     Only columns which have been converted to character will be quoted
     if specified by 'quote'.

     The 'dec' argument only applies to columns that are not subject to
     conversion to character because they have a class or are part of a
     matrix-like column (or matrix), in particular to columns protected
     by 'I()'.  Use 'options("OutDec")' to control such conversions.

     In almost all cases the conversion of numeric quantities is
     governed by the option '"scipen"' (see 'options'), but with the
     internal equivalent of 'digits=15'.  For finer control, use
     'format' to make a character matrix/data frame, and call
     'write.table' on that.

     These functions check for a user interrupt every 1000 lines of
     output.

     If 'file' is not open for writing, an attempt is made to open it
     and then close it after use.

CSV files:

     By default there is no column name for a column of row names.  If
     'col.names = NA' and 'row.names = TRUE' a blank column name is
     added, which is the convention used for CSV files to be read by
     spreadsheets.

     'write.csv' and 'write.csv2' provide convenience wrappers for
     writing CSV files.  They set 'sep', 'dec' and 'qmethod', and
     'col.names' to 'NA' if 'row.names = TRUE' and 'TRUE' otherwise.

     'write.csv' uses '"."' for the decimal point and a comma for the
     separator.

     'write.csv2' uses a comma for the decimal point and a semicolon
     for the separator, the Excel convention for CSV files in some
     Western European locales.

     These wrappers are deliberately inflexible: they are designed to
     ensure that the correct conventions are used to write a valid
     file. Attempts to change 'col.names', 'sep', 'dec' or 'qmethod'
     are ignored, with a warning.

Note:

     'write.table' can be slow for data frames with large numbers
     (hundreds or more) of columns: this is inevitable as each column
     could be of a different class and so must be handled separately. 
     If they are all of the same class, consider using a matrix
     instead.

See Also:

     The 'R Data Import/Export' manual.

     'read.table', 'write'.

     'write.matrix' in package 'MASS'.

Examples:

     ## Not run: 
     ## To write a CSV file for input to Excel one might use
     x <- data.frame(a = I("a \" quote"), b = pi)
     write.table(x, file = "foo.csv", sep = ",", col.names = NA,
                 qmethod = "double")
     ## and to read this file back into R one needs
     read.table("foo.csv", header = TRUE, sep = ",", row.names = 1)
     ## NB: you do need to specify a separator if qmethod = "double".

     ### Alternatively
     write.csv(x, file = "foo.csv")
     read.csv("foo.csv", row.names = 1)
     ## or without row names
     write.csv(x, file = "foo.csv", row.names = FALSE)
     read.csv("foo.csv")
     ## End(Not run)

