Nothing
README.md
In rio: A Swiss-Army Knife for Data I/O
rio: A Swiss-Army Knife for Data I/O 
Overview
The aim of rio is to make data file I/O in R as easy as possible by
implementing two main functions in Swiss-army knife style:
import() provides a painless data import experience by
automatically choosing the appropriate import/read function based on
file extension (or a specified format argument)export() provides the same painless file recognition for data
export/write functionality
Installation
The package is available on
CRAN and can be installed
directly in R using install.packages().
install.packages("rio")
The latest development version on GitHub can be installed using:
if (!require("remotes")){
install.packages("remotes")
}
remotes::install_github("gesistsa/rio")
Optional: Installation of additional formats (see below: Supported
file formats)
library(rio)
install_formats()
Usage
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.
Import
Importing data is handled with one function, import():
library("rio")
import("starwars.xlsx")
## Name homeworld species
## 1 Luke Skywalker Tatooine Human
## 2 C-3PO Tatooine Human
## 3 R2-D2 Alderaan Human
## 4 Darth Vader Tatooine Human
## 5 Leia Organa Tatooine Human
## 6 Owen Lars Tatooine Human
## 7 Beru Whitesun lars Stewjon Human
## 8 R5-D4 Tatooine Human
## 9 Biggs Darklighter Kashyyyk Wookiee
## 10 Obi-Wan Kenobi Corellia Human
import("starwars.csv")
## Name homeworld species
## 1 Luke Skywalker Tatooine Human
## 2 C-3PO Tatooine Human
## 3 R2-D2 Alderaan Human
## 4 Darth Vader Tatooine Human
## 5 Leia Organa Tatooine Human
## 6 Owen Lars Tatooine Human
## 7 Beru Whitesun lars Stewjon Human
## 8 R5-D4 Tatooine Human
## 9 Biggs Darklighter Kashyyyk Wookiee
## 10 Obi-Wan Kenobi Corellia Human
Export
Exporting data is handled with one function, export():
export(mtcars, "mtcars.csv") # comma-separated values
export(mtcars, "mtcars.rds") # R serialized
export(mtcars, "mtcars.sav") # SPSS
A particularly useful feature of rio is the ability to import from and
export to compressed archives (e.g., zip), saving users the extra step
of compressing a large exported file, e.g.:
export(mtcars, "mtcars.tsv.zip")
export() can also write multiple data frames to respective sheets of
an Excel workbook or an HTML file:
export(list(mtcars = mtcars, iris = iris), file = "mtcars.xlsx")
Supported file formats
rio supports a wide range of file formats. To keep the package slim,
several formats are supported via “Suggests” packages, which are not
installed (or loaded) by default. You can check which formats are
not supported via:
show_unsupported_formats()
You can install the suggested packages individually, depending your own
needs. If you want to install all suggested packages:
install_formats()
The full list of supported formats is below:
| Name | Extensions / “format” | Import Package | Export Package | Type | Note |
| :---------------------------------- | :---------------------------------- | :------------- | :------------- | :------ | :----------------------------- |
| Archive files (handled by tar) | tar / tar.gz / tgz / tar.bz2 / tbz2 | utils | utils | Default | |
| Bzip2 | bz2 / bzip2 | base | base | Default | |
| Gzip | gz / gzip | base | base | Default | |
| Zip files | zip | utils | utils | Default | |
| Ambiguous file format | dat | data.table | | Default | Attempt as delimited text data |
| CSVY (CSV + YAML metadata header) | csvy | data.table | data.table | Default | |
| Comma-separated data | csv | data.table | data.table | Default | |
| Comma-separated data (European) | csv2 | data.table | data.table | Default | |
| Data Interchange Format | dif | utils | | Default | |
| Epiinfo | epiinfo / rec | foreign | | Default | |
| Excel | excel / xlsx | readxl | writexl | Default | |
| Excel (Legacy) | xls | readxl | | Default | |
| Fixed-width format data | fwf | readr | utils | Default | |
| Fortran data | fortran | utils | | Default | No recognized extension |
| Google Sheets | googlesheets | data.table | | Default | As comma-separated data |
| Minitab | minitab / mtp | foreign | | Default | |
| Pipe-separated data | psv | data.table | data.table | Default | |
| R syntax | r | base | base | Default | |
| SAS | sas / sas7bdat | haven | haven | Default | Export is deprecated |
| SAS XPORT | xport / xpt | haven | haven | Default | |
| SPSS | sav / spss | haven | haven | Default | |
| SPSS (compressed) | zsav | haven | haven | Default | |
| SPSS Portable | por | haven | | Default | |
| Saved R objects | rda / rdata | base | base | Default | |
| Serialized R objects | rds | base | base | Default | |
| Stata | dta / stata | haven | haven | Default | |
| Systat | syd / systat | foreign | | Default | |
| Tab-separated data | / tsv / txt | data.table | data.table | Default | |
| Text Representations of R Objects | dump | base | base | Default | |
| Weka Attribute-Relation File Format | arff / weka | foreign | foreign | Default | |
| XBASE database files | dbf | foreign | foreign | Default | |
| Apache Arrow (Parquet) | parquet | nanoparquet | nanoparquet | Suggest | |
| Clipboard | clipboard | clipr | clipr | Suggest | default is tsv |
| EViews | eviews / wf1 | hexView | | Suggest | |
| Fast Storage | fst | fst | fst | Suggest | |
| Feather R/Python interchange format | feather | arrow | arrow | Suggest | |
| Graphpad Prism | pzfx | pzfx | pzfx | Suggest | |
| HTML Tables | htm / html | xml2 | xml2 | Suggest | |
| JSON | json | jsonlite | jsonlite | Suggest | |
| Matlab | mat / matlab | rmatio | rmatio | Suggest | |
| OpenDocument Spreadsheet | ods | readODS | readODS | Suggest | |
| OpenDocument Spreadsheet (Flat) | fods | readODS | readODS | Suggest | |
| Serialized R objects (Quick) | qs | qs | qs | Suggest | |
| Shallow XML documents | xml | xml2 | xml2 | Suggest | |
| YAML | yaml / yml | yaml | yaml | Suggest | |
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.
Other functions
Convert
The convert() function links import() and 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.
convert("mtcars.sav", "mtcars.dta")
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')"
*_list
import_list() allows users to import a list of data frames from a
multi-object file (such as an Excel workbook, .Rdata file, zip
directory, or HTML file):
str(m <- import_list("mtcars.xlsx"))
## List of 2
## $ mtcars:'data.frame': 32 obs. of 11 variables:
## ..$ mpg : num [1:32] 21 21 22.8 21.4 18.7 18.1 14.3 24.4 22.8 19.2 ...
## ..$ cyl : num [1:32] 6 6 4 6 8 6 8 4 4 6 ...
## ..$ disp: num [1:32] 160 160 108 258 360 ...
## ..$ hp : num [1:32] 110 110 93 110 175 105 245 62 95 123 ...
## ..$ drat: num [1:32] 3.9 3.9 3.85 3.08 3.15 2.76 3.21 3.69 3.92 3.92 ...
## ..$ wt : num [1:32] 2.62 2.88 2.32 3.21 3.44 ...
## ..$ qsec: num [1:32] 16.5 17 18.6 19.4 17 ...
## ..$ vs : num [1:32] 0 0 1 1 0 1 0 1 1 1 ...
## ..$ am : num [1:32] 1 1 1 0 0 0 0 0 0 0 ...
## ..$ gear: num [1:32] 4 4 4 3 3 3 3 4 4 4 ...
## ..$ carb: num [1:32] 4 4 1 1 2 1 4 2 2 4 ...
## $ iris :'data.frame': 150 obs. of 5 variables:
## ..$ Sepal.Length: num [1:150] 5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
## ..$ Sepal.Width : num [1:150] 3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
## ..$ Petal.Length: num [1:150] 1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
## ..$ Petal.Width : num [1:150] 0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
## ..$ Species : chr [1:150] "setosa" "setosa" "setosa" "setosa" ...
export_list() makes it easy to export a list of (possibly named) data
frames to multiple files:
export_list(m, "%s.tsv")
c("mtcars.tsv", "iris.tsv") %in% dir()
## [1] TRUE TRUE
Other projects
GUIs
- datamods provides
Shiny modules for importing data via
rio.
- 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.
Similar packages
- reader handles
certain text formats and R binary files
- io offers a set of
custom formats
- ImportExport
focuses on select binary formats (Excel, SPSS, and Access files) and
provides a Shiny interface.
- SchemaOnRead
iterates through a large number of possible import methods until one
works successfully
Try the rio package in your browser
Any scripts or data that you put into this service are public.
rio documentation built on Sept. 26, 2024, 1:07 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
rio: A Swiss-Army Knife for Data I/O
Overview
The aim of rio is to make data file I/O in R as easy as possible by implementing two main functions in Swiss-army knife style:
import()provides a painless data import experience by automatically choosing the appropriate import/read function based on file extension (or a specifiedformatargument)export()provides the same painless file recognition for data export/write functionality
Installation
The package is available on
CRAN and can be installed
directly in R using install.packages().
install.packages("rio")
The latest development version on GitHub can be installed using:
if (!require("remotes")){
install.packages("remotes")
}
remotes::install_github("gesistsa/rio")
Optional: Installation of additional formats (see below: Supported file formats)
library(rio)
install_formats()
Usage
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.
Import
Importing data is handled with one function, import():
library("rio")
import("starwars.xlsx")
## Name homeworld species
## 1 Luke Skywalker Tatooine Human
## 2 C-3PO Tatooine Human
## 3 R2-D2 Alderaan Human
## 4 Darth Vader Tatooine Human
## 5 Leia Organa Tatooine Human
## 6 Owen Lars Tatooine Human
## 7 Beru Whitesun lars Stewjon Human
## 8 R5-D4 Tatooine Human
## 9 Biggs Darklighter Kashyyyk Wookiee
## 10 Obi-Wan Kenobi Corellia Human
import("starwars.csv")
## Name homeworld species
## 1 Luke Skywalker Tatooine Human
## 2 C-3PO Tatooine Human
## 3 R2-D2 Alderaan Human
## 4 Darth Vader Tatooine Human
## 5 Leia Organa Tatooine Human
## 6 Owen Lars Tatooine Human
## 7 Beru Whitesun lars Stewjon Human
## 8 R5-D4 Tatooine Human
## 9 Biggs Darklighter Kashyyyk Wookiee
## 10 Obi-Wan Kenobi Corellia Human
Export
Exporting data is handled with one function, export():
export(mtcars, "mtcars.csv") # comma-separated values
export(mtcars, "mtcars.rds") # R serialized
export(mtcars, "mtcars.sav") # SPSS
A particularly useful feature of rio is the ability to import from and export to compressed archives (e.g., zip), saving users the extra step of compressing a large exported file, e.g.:
export(mtcars, "mtcars.tsv.zip")
export() can also write multiple data frames to respective sheets of
an Excel workbook or an HTML file:
export(list(mtcars = mtcars, iris = iris), file = "mtcars.xlsx")
Supported file formats
rio supports a wide range of file formats. To keep the package slim, several formats are supported via “Suggests” packages, which are not installed (or loaded) by default. You can check which formats are not supported via:
show_unsupported_formats()
You can install the suggested packages individually, depending your own needs. If you want to install all suggested packages:
install_formats()
The full list of supported formats is below:
| Name | Extensions / “format” | Import Package | Export Package | Type | Note | | :---------------------------------- | :---------------------------------- | :------------- | :------------- | :------ | :----------------------------- | | Archive files (handled by tar) | tar / tar.gz / tgz / tar.bz2 / tbz2 | utils | utils | Default | | | Bzip2 | bz2 / bzip2 | base | base | Default | | | Gzip | gz / gzip | base | base | Default | | | Zip files | zip | utils | utils | Default | | | Ambiguous file format | dat | data.table | | Default | Attempt as delimited text data | | CSVY (CSV + YAML metadata header) | csvy | data.table | data.table | Default | | | Comma-separated data | csv | data.table | data.table | Default | | | Comma-separated data (European) | csv2 | data.table | data.table | Default | | | Data Interchange Format | dif | utils | | Default | | | Epiinfo | epiinfo / rec | foreign | | Default | | | Excel | excel / xlsx | readxl | writexl | Default | | | Excel (Legacy) | xls | readxl | | Default | | | Fixed-width format data | fwf | readr | utils | Default | | | Fortran data | fortran | utils | | Default | No recognized extension | | Google Sheets | googlesheets | data.table | | Default | As comma-separated data | | Minitab | minitab / mtp | foreign | | Default | | | Pipe-separated data | psv | data.table | data.table | Default | | | R syntax | r | base | base | Default | | | SAS | sas / sas7bdat | haven | haven | Default | Export is deprecated | | SAS XPORT | xport / xpt | haven | haven | Default | | | SPSS | sav / spss | haven | haven | Default | | | SPSS (compressed) | zsav | haven | haven | Default | | | SPSS Portable | por | haven | | Default | | | Saved R objects | rda / rdata | base | base | Default | | | Serialized R objects | rds | base | base | Default | | | Stata | dta / stata | haven | haven | Default | | | Systat | syd / systat | foreign | | Default | | | Tab-separated data | / tsv / txt | data.table | data.table | Default | | | Text Representations of R Objects | dump | base | base | Default | | | Weka Attribute-Relation File Format | arff / weka | foreign | foreign | Default | | | XBASE database files | dbf | foreign | foreign | Default | | | Apache Arrow (Parquet) | parquet | nanoparquet | nanoparquet | Suggest | | | Clipboard | clipboard | clipr | clipr | Suggest | default is tsv | | EViews | eviews / wf1 | hexView | | Suggest | | | Fast Storage | fst | fst | fst | Suggest | | | Feather R/Python interchange format | feather | arrow | arrow | Suggest | | | Graphpad Prism | pzfx | pzfx | pzfx | Suggest | | | HTML Tables | htm / html | xml2 | xml2 | Suggest | | | JSON | json | jsonlite | jsonlite | Suggest | | | Matlab | mat / matlab | rmatio | rmatio | Suggest | | | OpenDocument Spreadsheet | ods | readODS | readODS | Suggest | | | OpenDocument Spreadsheet (Flat) | fods | readODS | readODS | Suggest | | | Serialized R objects (Quick) | qs | qs | qs | Suggest | | | Shallow XML documents | xml | xml2 | xml2 | Suggest | | | YAML | yaml / yml | yaml | yaml | Suggest | |
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.
Other functions
Convert
The convert() function links import() and 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.
convert("mtcars.sav", "mtcars.dta")
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')"
*_list
import_list() allows users to import a list of data frames from a
multi-object file (such as an Excel workbook, .Rdata file, zip
directory, or HTML file):
str(m <- import_list("mtcars.xlsx"))
## List of 2
## $ mtcars:'data.frame': 32 obs. of 11 variables:
## ..$ mpg : num [1:32] 21 21 22.8 21.4 18.7 18.1 14.3 24.4 22.8 19.2 ...
## ..$ cyl : num [1:32] 6 6 4 6 8 6 8 4 4 6 ...
## ..$ disp: num [1:32] 160 160 108 258 360 ...
## ..$ hp : num [1:32] 110 110 93 110 175 105 245 62 95 123 ...
## ..$ drat: num [1:32] 3.9 3.9 3.85 3.08 3.15 2.76 3.21 3.69 3.92 3.92 ...
## ..$ wt : num [1:32] 2.62 2.88 2.32 3.21 3.44 ...
## ..$ qsec: num [1:32] 16.5 17 18.6 19.4 17 ...
## ..$ vs : num [1:32] 0 0 1 1 0 1 0 1 1 1 ...
## ..$ am : num [1:32] 1 1 1 0 0 0 0 0 0 0 ...
## ..$ gear: num [1:32] 4 4 4 3 3 3 3 4 4 4 ...
## ..$ carb: num [1:32] 4 4 1 1 2 1 4 2 2 4 ...
## $ iris :'data.frame': 150 obs. of 5 variables:
## ..$ Sepal.Length: num [1:150] 5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ...
## ..$ Sepal.Width : num [1:150] 3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ...
## ..$ Petal.Length: num [1:150] 1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ...
## ..$ Petal.Width : num [1:150] 0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ...
## ..$ Species : chr [1:150] "setosa" "setosa" "setosa" "setosa" ...
export_list() makes it easy to export a list of (possibly named) data
frames to multiple files:
export_list(m, "%s.tsv")
c("mtcars.tsv", "iris.tsv") %in% dir()
## [1] TRUE TRUE
Other projects
GUIs
- datamods provides
Shiny modules for importing data via
rio. - 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.
Similar packages
- reader handles certain text formats and R binary files
- io offers a set of custom formats
- ImportExport focuses on select binary formats (Excel, SPSS, and Access files) and provides a Shiny interface.
- SchemaOnRead iterates through a large number of possible import methods until one works successfully
Try the rio package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.