export: Export

Description

Write data.frame to a file

Usage

export(x, file, format, ...)

Value

The name of the output file as a character string (invisibly).

Arguments

x: A data frame or matrix to be written into a file. Exceptions to this rule are that x can be a list of data frames if the output file format is an Excel .xlsx workbook, .Rdata file, or HTML file, or a variety of R objects if the output file format is RDS or JSON. See examples.) To export a list of data frames to multiple files, use export_list instead.
file: A character string naming a file. Must specify file and/or format.
format: An optional character string containing the file format, which can be used to override the format inferred from file or, in lieu of specifying file, a file with the symbol name of x and the specified file extension will be created. Must specify file and/or format. Shortcuts include: “,” (for comma-separated values), “;” (for semicolon-separated values), “|” (for pipe-separated values), and “dump” for dump.
...: Additional arguments for the underlying export functions. This can be used to specify non-standard arguments. See examples.

Details

This function exports a data frame or matrix into a file with file format based on the file extension (or the manually specified format, if format is specified).

The output file can be to a compressed directory, simply by adding an appropriate additional extensiont to the file argument, such as: “mtcars.csv.tar”, “mtcars.csv.zip”, or “mtcars.csv.gz”.

export supports many file formats. See the documentation for the underlying export functions for optional arguments that can be passed via ...

Comma-separated data (.csv), using fwrite or, if fwrite = TRUE, write.table with row.names = FALSE.
Pipe-separated data (.psv), using fwrite or, if fwrite = TRUE, write.table with sep = '|' and row.names = FALSE.
Tab-separated data (.tsv), using fwrite or, if fwrite = TRUE, write.table with row.names = FALSE.
SAS (.sas7bdat), using write_sas.
SAS XPORT (.xpt), using write_xpt.
SPSS (.sav), using write_sav
SPSS compressed (.zsav), using write_sav
Stata (.dta), using write_dta. Note that variable/column names containing dots (.) are not allowed and will produce an error.
Excel (.xlsx), using write.xlsx. Existing workbooks are overwritten unless which is specified, in which case only the specified sheet (if it exists) is overwritten. If the file exists but the which sheet does not, data are added as a new sheet to the existing workbook. x can also be a list of data frames; the list entry names are used as sheet names.
R syntax object (.R), using dput (by default) or dump (if format = 'dump')
Saved R objects (.RData,.rda), using save. In this case, x can be a data frame, a named list of objects, an R environment, or a character vector containing the names of objects if a corresponding envir argument is specified.
Serialized R objects (.rds), using saveRDS. In this case, x can be any serializable R object.
"XBASE" database files (.dbf), using write.dbf
Weka Attribute-Relation File Format (.arff), using write.arff
Fixed-width format data (.fwf), using write.table with row.names = FALSE, quote = FALSE, and col.names = FALSE
gzip comma-separated data (.csv.gz), using write.table with row.names = FALSE
CSVY (CSV with a YAML metadata header) using fwrite.
Apache Arrow Parquet (.parquet), using write_parquet
Feather R/Python interchange format (.feather), using write_feather
Fast storage (.fst), using write.fst
JSON (.json), using toJSON. In this case, x can be a variety of R objects, based on class mapping conventions in this paper: https://arxiv.org/abs/1403.2805.
Matlab (.mat), using write.mat
OpenDocument Spreadsheet (.ods), using write_ods. (Currently only single-sheet exports are supported.)
HTML (.html), using a custom method based on xml_add_child to create a simple HTML table and write_xml to write to disk.
XML (.xml), using a custom method based on xml_add_child to create a simple XML tree and write_xml to write to disk.
YAML (.yml), using as.yaml
Clipboard export (on Windows and Mac OS), using write.table with row.names = FALSE

When exporting a data set that contains label attributes (e.g., if imported from an SPSS or Stata file) to a plain text file, characterize can be a useful pre-processing step that records value labels into the resulting file (e.g., export(characterize(x), "file.csv")) rather than the numeric values.

Use export_list to export a list of dataframes to separate files.

Examples

Run this code

library("datasets")
# specify only `file` argument
export(mtcars, f1 <- tempfile(fileext = ".csv"))

if (FALSE) {
wd <- getwd()
setwd(tempdir())
# Stata does not recognize variables names with '.'
export(mtcars, f2 <- tempfile(fileext = ".dta"))

# specify only `format` argument
f2 %in% tempdir()
export(mtcars, format = "stata")
"mtcars.dta" %in% dir()

setwd(wd)
}
# specify `file` and `format` to override default format
export(mtcars, file = f3 <- tempfile(fileext = ".txt"), format = "csv")

# export multiple objects to Rdata
export(list(mtcars = mtcars, iris = iris), f4 <- tempfile(fileext = ".rdata"))
export(c("mtcars", "iris"), f4)

# export to non-data frame R object to RDS or JSON
export(mtcars$cyl, f5 <- tempfile(fileext = ".rds"))
export(list(iris, mtcars), f6 <- tempfile(fileext = ".json"))

# pass arguments to underlying export function
export(mtcars, f7 <- tempfile(fileext = ".csv"), col.names = FALSE)

# write data to .R syntax file and append additional data
export(mtcars, file = f8 <- tempfile(fileext = ".R"), format = "dump")
export(mtcars, file = f8, format = "dump", append = TRUE)
source(f8, echo = TRUE)

# write to an Excel workbook
if (FALSE) {
  ## export a single data frame
  export(mtcars, f9 <- tempfile(fileext = ".xlsx"))
  
  ## export NAs to Excel as missing via args passed to `...`
  mtcars$drat <- NA_real_
  mtcars %>% export(f10 <- tempfile(fileext = ".xlsx"), keepNA = TRUE)
  
  ## export a list of data frames as worksheets
  export(list(a = mtcars, b = iris), f11 <- tempfile(fileext = ".xlsx"))

  ## export, adding a new sheet to an existing workbook
  export(iris, f12 <- tempfile(fileext = ".xlsx"), which = "iris")
}

# write data to a zip-compressed CSV
export(mtcars, f13 <- tempfile(fileext = ".csv.zip"))

# cleanup
unlink(f1)
# unlink(f2)
unlink(f3)
unlink(f4)
unlink(f5)
unlink(f6)
unlink(f7)
unlink(f8)
# unlink(f9)
# unlink(f10)
# unlink(f11)
# unlink(f12)
# unlink(f13)