Streamlined data import and export by making assumptions that the user is probably willing to make: 'import()' and 'export()' determine the data structure from the file extension, reasonable defaults are used for data import and export (e.g., 'stringsAsFactors=FALSE'), web-based import is natively supported (including from SSL/HTTPS), compressed files can be read directly without explicit decompression, and fast import packages are used where appropriate. An additional convenience function, 'convert()', provides a simple method for converting between file types.
The aim of rio is to make data file I/O in R as easy as possible by implementing three simple functions in Swiss-army knife style:
import()provide a painless data I/O experience by automatically choosing the appropriate data read or write function based on file extension
export()to allow the user to easily convert between file formats (thus providing a FOSS replacement for programs like Stat/Transfer or Sledgehammer). Luca Braglia has created a Shiny app called rioweb that provides access to the file conversion features of rio. GREA is an RStudio add-in that provides an interactive interface for reading in data using rio.
rio supports a variety of different file formats for import and export.
|Tab-separated data (.tsv)||Yes||Yes|
|Comma-separated data (.csv)||Yes||Yes|
|CSVY (CSV + YAML metadata header) (.csvy)||Yes||Yes|
|Feather R/Python interchange format (.feather)||Yes||Yes|
|Pipe-separated data (.psv)||Yes||Yes|
|Fixed-width format data (.fwf)||Yes||Yes|
|Serialized R objects (.rds)||Yes||Yes|
|Saved R objects (.RData)||Yes||Yes|
|SPSS Portable (.por)||Yes|
|"XBASE" database files (.dbf)||Yes||Yes|
|Weka Attribute-Relation File Format (.arff)||Yes||Yes|
|R syntax (.R)||Yes||Yes|
|Shallow XML documents (.xml)||Yes||Yes|
|HTML Tables (.html)||Yes||Yes|
|SAS XPORT (.xpt)||Yes|
|Data Interchange Format (.dif)||Yes|
|OpenDocument Spreadsheet (.ods)||Yes|
|Fortran data (no recognized extension)||Yes|
|Clipboard (default is tsv)||Yes (Mac and Windows)||Yes (Mac and Windows)|
Additionally, any format that is not supported by rio but that has a known R implementation will produce an informative error message pointing to a package and import or export function. Unrecognized formats will yield a simple "Unrecognized file format" error.
Because rio is meant to streamline data I/O, the package is extremely easy to use. Here are some examples of reading, writing, and converting data files.
Exporting data is handled with one function,
library("rio")export(mtcars, "mtcars.csv") # comma-separated valuesexport(mtcars, "mtcars.rds") # R serializedexport(mtcars, "mtcars.sav") # SPSS
Importing data is handled with one function,
x <- import("mtcars.csv")y <- import("mtcars.rds")z <- import("mtcars.sav")# confirm data matchall.equal(x, y, check.attributes = FALSE)
##  TRUE
all.equal(x, z, check.attributes = FALSE)
##  TRUE
Note: Because of inconsistencies across underlying packages, the data.frame returned by
import might vary slightly (in variable classes and attributes) depending on file type.
convert() function links
export() by constructing a dataframe from the imported file and immediately writing it back to disk.
convert() invisibly returns the file name of the exported file, so that it can be used to programmatically access the new file.
It is also possible to use rio on the command-line by calling
Rscript with the
-e (expression) argument. For example, to convert a file from Stata (.dta) to comma-separated values (.csv), simply do the following:
Rscript -e "rio::convert('iris.dta', 'iris.csv')"
The core advantage of rio is that it makes assumptions that the user is probably willing to make. Eight of these are important:
data.table::fread() for text-delimited files to automatically determine the file format regardless of the extension. So, a CSV that is actually tab-separated will still be correctly imported. It's also crazy fast.
rio, wherever possible, does not import character strings as factors.
rio stores metadata from rich file formats (SPSS, Stata, etc.) in variable-level attributes in a consistent form regardless of file type or underlying import function. The
gather_attrs() function makes it easy to move variable-level attributes to the data frame level.
rio supports web-based imports natively, including from SSL (HTTPS) URLs, from shortened URLs, from URLs that lack proper extensions, and from (public) Google Documents Spreadsheets.
rio imports from from single-file .zip and .tar archives automatically, without the need to explicitly decompress them. Export to compressed directories is also supported.
rio imports and exports files based on an internal S3 class infrastructure. This means that other packages can contain extensions to rio by registering S3 methods. These methods should take the form
X is the file extension of a file type. An example is provided in the rio.db package.
rio wraps a variety of faster, more stream-lined I/O packages than those provided by base R or the foreign package. It uses haven for reading and writing SAS, Stata, and SPSS files, the
fread function from data.table for delimited formats, smarter and faster fixed-width file import and export routines, and readxl for reading from Excel workbooks.
The package is available on CRAN and can be installed directly in R using:
The latest development version on GitHub can be installed using devtools:
export()with respect to unrecognized file types. (#124, #125, h/t Jason Becker)
options(datatable.fread.dec.experiment=FALSE)during onLoad to address a Unix-specific locale issue.
separgument for import of delimited files. (#99, h/t Danny Parsons)
featherdata serialization format. (#88, h/t Jason Becker)
gather_attrs()on a data.frame with no attributes to gather. (#94)
gather_attrs()function that moves variable-level attributes to the data.frame level. (#80)
readr::read_fwf()with a specified
widthsargument. This may enable faster import of these types of files and provides a base-like interface for working with readr. (#48)
.export()are now exported S3 generics and documentation has been added to describe how to write rio extensions for new file types. An example of this functionality is shown in the new suggested "rio.db" package.
import()now uses xml2 to read XML structures and
export()uses a custom method for writing to XML, thereby negating dependency on the XML package. (#67)
whichargument that is used to select which file to return from within a compressed tar or zip archive.
tar()that are being fixed in base R via PR#16716.
import()(introduced in #62, 7a7480e5) that prevented import from clipboard. (h/t Kevin Wright)
export()returns a character string. (#82)
import()for SAS, Stata, and SPSS files has been streamlined. Regardless of whether the
haven = TRUEargument is used, the data.frame returned by
import()should now be (nearly) identical, with all attributes stored at the variable rather than data.frame level. This is a non-backwards compatible change. (#80)
export()now allows automatic file compression as tar, gzip, or zip using the
export()for fixed-width format files and added a commented header containing column class and width information.
.export.default()then produce an error. This enables add-on packages to support additional formats through new s3 methods of the form
.export()methods. (#42, h/t Jason Becker)
curl::curl_fetch_memory(), the HTTP headers are checked for a filename in the Content-Disposition header. (#36)
urltools::url_parse()to extract file extensions from complex URLs (e.g., those with query arguments). (#56)
Suggeststo remove an
importalways returns a data.frame, unless
setclassis specified. (#22)
readxl::read_excel, making its use optional. (#19)
data.table::freadby default for reading delimited files. (#3)
stringsAsFactors = FALSEas default for reading tabular data. (#4)
exportbased on object name and file format. (#5)
convert, and utilities into separate source code files.