rio (version 0.5.10)

export: Export

Description

Write data.frame to a file

Usage

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

Arguments

x

A data frame or matrix to be written into a file. (An exception to this is that x can be a list of data frames if the output file format is an Excel .xlsx workbook, .Rdata file, or HTML file. See examples.)

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. See examples.

Value

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

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

• 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. Use which to specify a sheet name and overwrite to decide whether to overwrite an existing file or worksheet (the default) or add the data as a new worksheet (with overwrite = FALSE). 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

• "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 write_csvy. The YAML header lines are preceded by R comment symbols (#) by default; this can be turned off by passing a comment_header = FALSE argument to export. Setting fwrite = TRUE (the default) will rely on fwrite for much faster export.

• Feather R/Python interchange format (.feather), using write_feather

• Fast storage (.fst), using write.fst

• JSON (.json), using toJSON

• 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.

See Also

.export, characterize, import, convert

Examples

# NOT RUN {
library("datasets")
# specify only `file` argument
export(mtcars, "mtcars.csv")

# }
# NOT RUN {
# Stata does not recognize variables names with '.'
export(mtcars, "mtcars.dta")
# }
# NOT RUN {
# specify only `format` argument
"mtcars.dta" %in% dir()
export(mtcars, format = "stata")
"mtcars.dta" %in% dir()

# specify `file` and `format` to override default format
export(mtcars, file = "mtcars.txt", format = "csv")

# export multiple objects to Rdata
export(list(mtcars = mtcars, iris = iris), "mtcars.rdata")
export(c("mtcars", "iris"), "mtcars.rdata")

# export to JSON
export(mtcars, "mtcars.json")

# pass arguments to underlying export function
export(mtcars, "mtcars.csv", col.names = FALSE)

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

# write to an Excel workbook
# }
# NOT RUN {
  ## export a single data frame
  export(mtcars, "mtcars.xlsx")
  
  ## export a list of data frames as worksheets
  export(list(a = mtcars, b = iris), "multisheet.xlsx")

  ## export, adding sheet to an existing workbook
  export(iris, "mtcars.xlsx", which = "iris", overwrite = FALSE)
# }
# NOT RUN {
# write data to a zip-compressed CSV
export(mtcars, "mtcars.csv.zip")

# cleanup
unlink("mtcars.csv")
unlink("mtcars.dta")
unlink("mtcars.json")
unlink("mtcars.rdata")
unlink("data.R")
unlink("mtcars.csv.zip")
# }