export {rio}

Export

Description

Write data.frame to a file

Usage

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

Arguments

x

A data frame, matrix or a single-item list of data frame to be written into a file. Exceptions to this rule are that x can be a list of multiple data frames if the output file format is an OpenDocument Spreadsheet (.ods, .fods), 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 base::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 data.table::fwrite()

• Pipe-separated data (.psv), using data.table::fwrite()

• Tab-separated data (.tsv), using data.table::fwrite()

• SAS (.sas7bdat), using haven::write_sas().

• SAS XPORT (.xpt), using haven::write_xpt().

• SPSS (.sav), using haven::write_sav()

• SPSS compressed (.zsav), using haven::write_sav()

• Stata (.dta), using haven::write_dta(). Note that variable/column names containing dots (.) are not allowed and will produce an error.

• Excel (.xlsx), using writexl::write_xlsx(). x can also be a list of data frames; the list entry names are used as sheet names.

• R syntax object (.R), using base::dput() (by default) or base::dump() (if format = 'dump')

• Saved R objects (.RData,.rda), using base::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 base::saveRDS(). In this case, x can be any serializable R object.

• Serialized R objects (.qs), using qs::qsave(), which is significantly faster than .rds. This can be any R object (not just a data frame).

• "XBASE" database files (.dbf), using foreign::write.dbf()

• Weka Attribute-Relation File Format (.arff), using foreign::write.arff()

• Fixed-width format data (.fwf), using utils::write.table() with row.names = FALSE, quote = FALSE, and col.names = FALSE

• CSVY (CSV with a YAML metadata header) using data.table::fwrite().

• Apache Arrow Parquet (.parquet), using nanoparquet::write_parquet()

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

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

• JSON (.json), using jsonlite::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 rmatio::write.mat()

• OpenDocument Spreadsheet (.ods, .fods), using readODS::write_ods() or readODS::write_fods().

• HTML (.html), using a custom method based on xml2::xml_add_child() to create a simple HTML table and xml2::write_xml() to write to disk.

• XML (.xml), using a custom method based on xml2::xml_add_child() to create a simple XML tree and xml2::write_xml() to write to disk.

• YAML (.yml), using yaml::write_yaml(), default to write the content with UTF-8. Might not work on some older systems, e.g. default Windows locale for R <= 4.2.

• Clipboard export (on Windows and Mac OS), using utils::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.

Value

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

See Also

characterize(), import(), convert(), export_list()

Examples

## For demo, a temp. file path is created with the file extension .csv
csv_file <- tempfile(fileext = ".csv")
## .xlsx
xlsx_file <- tempfile(fileext = ".xlsx")

## create CSV to import
export(iris, csv_file)

## You can certainly export your data with the file name, which is not a variable:
## import(mtcars, "car_data.csv")

## pass arguments to the underlying function
## data.table::fwrite is the underlying function and `col.names` is an argument
export(iris, csv_file, col.names = FALSE)

## export a list of data frames as worksheets
export(list(a = mtcars, b = iris), xlsx_file)

# NOT RECOMMENDED

## specify `format` to override default format
export(iris, xlsx_file, format = "csv") ## That's confusing
## You can also specify only the format; in the following case
## "mtcars.dta" is written [also confusing]

## export(mtcars, format = "stata")