R: Data Output

write.table {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"),
                fileEncoding = "")

    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 Excel:mac 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 for `write.table`), in which case the quote character is escaped in C style by a backslash, or `"double"` (default for `write.csv` and `write.csv2`), in which case it is doubled. You can specify just the initial letter.
`fileEncoding` | character string: if non-empty declares the encoding to be used on a file (not a connection) so the character data can be re-encoded as they are written. See `file`.
`...` | arguments to `write.table`: `append`, `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 a non-open connection, an attempt is made to open it and then close it after use.

To write a Unix-style file on Windows, use a binary connection e.g. `file = file("filename", "wb")`.

### 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. Note that such CSV files can be read in R by

      read.csv(file = "<filename>", row.names = 1)

`write.csv` and `write.csv2` provide convenience wrappers for writing CSV files. They set `sep` and `dec` (see below), `qmethod = "double"`, and `col.names` to `NA` if `row.names = TRUE` (the default) and to `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 `append`, `col.names`, `sep`, `dec` or `qmethod` are ignored, with a warning. CSV files do not record an encoding, and this causes problems if they are not ASCII for many other applications. Windows Excel 2007/10 will open files (e.g. by the file association mechanism) correctly if they are ASCII or UTF-16 (use `fileEncoding = "UTF-16LE"`) or perhaps in the current Windows codepage (e.g. `"CP1252"`), but the ‘Text Import Wizard’ (from the ‘Data’ tab) allows far more choice of encodings. Excel:mac 2004/8 can import only Macintosh (which seems to mean MacRoman), Windows (perhaps Latin-1) and ‘PC-8’ files. OpenOffice 3.x asks for the character set when opening the file. There is an IETF RFC4180 (http://tools.ietf.org/html/rfc4180) for CSV files, which mandates comma as the separator and CRLF line endings. `write.csv` writes compliant files on Windows: use `eol="\r\n"` on other platforms.

### 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")

    ## To write a file in MacRoman for simple use in Mac Excel 2004/8
    write.csv(x, file = "foo.csv", fileEncoding = "macroman")
    ## or for Windows Excel 2007/10
    write.csv(x, file = "foo.csv", fileEncoding = "UTF-16LE")

    ## End(Not run)

[Package utils version 2.15.1 Index]