-
Notifications
You must be signed in to change notification settings - Fork 77
/
README.Rmd
176 lines (121 loc) · 6.25 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
---
output: github_document
---
# rio: A Swiss-Army Knife for Data I/O <img src="man/figures/logo.png" align="right" height="139"/>
<!-- badges: start -->
[](https://cran.r-project.org/package=rio)
<!-- badges: end -->
## 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](https://cran.r-project.org/package=rio) and can be installed directly in R using `install.packages()`.
```R
install.packages("rio")
```
The latest development version on GitHub can be installed using:
```R
if (!require("remotes")){
install.packages("remotes")
}
remotes::install_github("gesistsa/rio")
```
Optional: Installation of additional formats (see below: **Supported file formats**)
```R
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()`:
```{r import1}
library("rio")
import("starwars.xlsx")
```
```{r import2}
import("starwars.csv")
```
### Export
Exporting data is handled with one function, `export()`:
```{r exports}
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.:
```{r export_zip}
export(mtcars, "mtcars.tsv.zip")
```
`export()` can also write multiple data frames to respective sheets of an Excel workbook or an HTML file:
```{r export_a_list}
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. To ensure rio is fully functional, install these packages the first time you use **rio** via:
```R
install_formats()
```
The full list of supported formats is below:
```{r, include = FALSE}
suppressPackageStartupMessages(library(data.table))
```
```{r featuretable, echo = FALSE}
rf <- data.table(rio:::rio_formats)[!input %in% c(",", ";", "|", "\\t") & type %in% c("import", "suggest", "archive"),]
short_rf <- rf[, paste(input, collapse = " / "), by = format_name]
type_rf <- unique(rf[,c("format_name", "type", "import_function", "export_function", "note")])
feature_table <- short_rf[type_rf, on = .(format_name)]
colnames(feature_table)[2] <- "signature"
setorder(feature_table, "type", "format_name")
feature_table$import_function <- stringi::stri_extract_first(feature_table$import_function, regex = "[a-zA-Z0-9\\.]+")
feature_table$import_function[is.na(feature_table$import_function)] <- ""
feature_table$export_function <- stringi::stri_extract_first(feature_table$export_function, regex = "[a-zA-Z0-9\\.]+")
feature_table$export_function[is.na(feature_table$export_function)] <- ""
feature_table$type <- ifelse(feature_table$type %in% c("suggest"), "Suggest", "Default")
feature_table <- feature_table[,c("format_name", "signature", "import_function", "export_function", "type", "note")]
colnames(feature_table) <- c("Name", "Extensions / \"format\"", "Import Package", "Export Package", "Type", "Note")
knitr::kable(feature_table)
```
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.
```{r convert}
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):
```{r import_list}
str(m <- import_list("mtcars.xlsx"))
```
`export_list()` makes it easy to export a list of (possibly named) data frames to multiple files:
```{r export_list}
export_list(m, "%s.tsv")
c("mtcars.tsv", "iris.tsv") %in% dir()
```
```{r cleanup, echo=FALSE, results="hide"}
unlink("mtcars.csv")
unlink("mtcars.dta")
unlink("mtcars.sav")
unlink("mtcars.rds")
unlink("mtcars.xlsx")
unlink("mtcars.tsv.zip")
unlink("mtcars.tsv")
unlink("iris.tsv")
```
## Other projects
### GUIs
* [**datamods**](https://cran.r-project.org/package=datamods) provides Shiny modules for importing data via `rio`.
* [**rioweb**](https://github.com/lbraglia/rioweb) that provides access to the file conversion features of `rio`.
* [**GREA**](https://github.com/Stan125/GREA/) is an RStudio add-in that provides an interactive interface for reading in data using `rio`.
### Similar packages
* [**reader**](https://cran.r-project.org/package=reader) handles certain text formats and R binary files
* [**io**](https://cran.r-project.org/package=io) offers a set of custom formats
* [**ImportExport**](https://cran.r-project.org/package=ImportExport) focuses on select binary formats (Excel, SPSS, and Access files) and provides a Shiny interface.
* [**SchemaOnRead**](https://cran.r-project.org/package=SchemaOnRead) iterates through a large number of possible import methods until one works successfully