rio/ 0000755 0001762 0000144 00000000000 14502301742 011041 5 ustar ligges users rio/NAMESPACE 0000644 0001762 0000144 00000004556 14500613454 012276 0 ustar ligges users # Generated by roxygen2: do not edit by hand
S3method(.export,rio_arff)
S3method(.export,rio_clipboard)
S3method(.export,rio_csv)
S3method(.export,rio_csv2)
S3method(.export,rio_csvy)
S3method(.export,rio_dbf)
S3method(.export,rio_dta)
S3method(.export,rio_dump)
S3method(.export,rio_feather)
S3method(.export,rio_fods)
S3method(.export,rio_fst)
S3method(.export,rio_fwf)
S3method(.export,rio_html)
S3method(.export,rio_json)
S3method(.export,rio_matlab)
S3method(.export,rio_ods)
S3method(.export,rio_parquet)
S3method(.export,rio_psv)
S3method(.export,rio_pzfx)
S3method(.export,rio_qs)
S3method(.export,rio_r)
S3method(.export,rio_rda)
S3method(.export,rio_rdata)
S3method(.export,rio_rds)
S3method(.export,rio_sas7bdat)
S3method(.export,rio_sav)
S3method(.export,rio_tsv)
S3method(.export,rio_txt)
S3method(.export,rio_xlsx)
S3method(.export,rio_xml)
S3method(.export,rio_xpt)
S3method(.export,rio_yml)
S3method(.export,rio_zsav)
S3method(.import,rio_arff)
S3method(.import,rio_clipboard)
S3method(.import,rio_csv)
S3method(.import,rio_csv2)
S3method(.import,rio_csvy)
S3method(.import,rio_dat)
S3method(.import,rio_dbf)
S3method(.import,rio_dif)
S3method(.import,rio_dta)
S3method(.import,rio_dump)
S3method(.import,rio_eviews)
S3method(.import,rio_feather)
S3method(.import,rio_fods)
S3method(.import,rio_fortran)
S3method(.import,rio_fst)
S3method(.import,rio_fwf)
S3method(.import,rio_html)
S3method(.import,rio_json)
S3method(.import,rio_matlab)
S3method(.import,rio_mtp)
S3method(.import,rio_ods)
S3method(.import,rio_parquet)
S3method(.import,rio_psv)
S3method(.import,rio_pzfx)
S3method(.import,rio_qs)
S3method(.import,rio_r)
S3method(.import,rio_rda)
S3method(.import,rio_rdata)
S3method(.import,rio_rds)
S3method(.import,rio_rec)
S3method(.import,rio_sas7bdat)
S3method(.import,rio_sav)
S3method(.import,rio_spss)
S3method(.import,rio_syd)
S3method(.import,rio_tsv)
S3method(.import,rio_txt)
S3method(.import,rio_xls)
S3method(.import,rio_xlsx)
S3method(.import,rio_xml)
S3method(.import,rio_xpt)
S3method(.import,rio_yml)
S3method(.import,rio_zsav)
S3method(characterize,data.frame)
S3method(characterize,default)
S3method(factorize,data.frame)
S3method(factorize,default)
export(characterize)
export(convert)
export(export)
export(export_list)
export(factorize)
export(gather_attrs)
export(get_ext)
export(get_info)
export(import)
export(import_list)
export(install_formats)
export(spread_attrs)
rio/README.md 0000644 0001762 0000144 00000031627 14502270161 012331 0 ustar ligges users
# rio: A Swiss-Army Knife for Data I/O
[](https://cran.r-project.org/package=rio)

## 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
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
``` r
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
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.
### Export
Exporting data is handled with one function, `export()`:
``` r
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 (e.g., zip) directories, saving users the extra
step of compressing a large exported file, e.g.:
``` r
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(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:
| Name | Extensions / “format” | Import Package | Export Package | Type | Note |
| :---------------------------------- | :-------------------- | :------------- | :------------- | :------ | :---------------------- |
| Archive files (handled by tar) | bzip2 / xz / tar | utils | utils | Default | |
| Gzip files | gz / gzip | base | base | Default | |
| Zip files | zip | utils | utils | Default | |
| 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 | utils | 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 | arrow | arrow | 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.
``` r
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
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:
``` r
export_list(m, "%s.tsv")
c("mtcars.tsv", "iris.tsv") %in% dir()
```
## [1] TRUE TRUE
## Other projects
### GUIs
- [**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
rio/man/ 0000755 0001762 0000144 00000000000 14502270161 011614 5 ustar ligges users rio/man/import.Rd 0000644 0001762 0000144 00000023370 14502270161 013422 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/import.R
\name{import}
\alias{import}
\title{Import}
\usage{
import(
file,
format,
setclass = getOption("rio.import.class", "data.frame"),
which,
...
)
}
\arguments{
\item{file}{A character string naming a file, URL, or single-file .zip or .tar archive.}
\item{format}{An optional character string code of file format, which can be used to override the format inferred from \code{file}. Shortcuts include: \dQuote{,} (for comma-separated values), \dQuote{;} (for semicolon-separated values), and \dQuote{|} (for pipe-separated values).}
\item{setclass}{An optional character vector specifying one or more classes
to set on the import. By default, the return object is always a
\dQuote{data.frame}. Allowed values include \dQuote{tbl_df}, \dQuote{tbl}, or
\dQuote{tibble} (if using tibble), \dQuote{arrow}, \dQuote{arrow_table} (if using arrow table; the suggested package \code{arrow} must be installed) or \dQuote{data.table} (if using
data.table). Other values are ignored, such that a data.frame is returned.
The parameter takes precedents over parameters in \dots which set a different class.}
\item{which}{This argument is used to control import from multi-object files; as a rule \code{import} only ever returns a single data frame (use \code{\link[=import_list]{import_list()}} to import multiple data frames from a multi-object file). If \code{file} is a compressed directory, \code{which} can be either a character string specifying a filename or an integer specifying which file (in locale sort order) to extract from the compressed directory. For Excel spreadsheets, this can be used to specify a sheet name or number. For .Rdata files, this can be an object name. For HTML files, it identifies which table to extract (from document order). Ignored otherwise. A character string value will be used as a regular expression, such that the extracted file is the first match of the regular expression against the file names in the archive.}
\item{\dots}{Additional arguments passed to the underlying import functions. For example, this can control column classes for delimited file types, or control the use of haven for Stata and SPSS or readxl for Excel (.xlsx) format. See details below.}
}
\value{
A data frame. If \code{setclass} is used, this data frame may have additional class attribute values, such as \dQuote{tibble} or \dQuote{data.table}.
}
\description{
Read in a data.frame from a file. Exceptions to this rule are Rdata, RDS, and JSON input file formats, which return the originally saved object without changing its class.
}
\details{
This function imports a data frame or matrix from a data file with the file format based on the file extension (or the manually specified format, if \code{format} is specified).
\code{import} supports the following file formats:
\itemize{
\item Comma-separated data (.csv), using \code{\link[data.table:fread]{data.table::fread()}}
\item Pipe-separated data (.psv), using \code{\link[data.table:fread]{data.table::fread()}}
\item Tab-separated data (.tsv), using \code{\link[data.table:fread]{data.table::fread()}}
\item SAS (.sas7bdat), using \code{\link[haven:read_sas]{haven::read_sas()}}
\item SAS XPORT (.xpt), using \code{\link[haven:read_xpt]{haven::read_xpt()}}
\item SPSS (.sav), using \code{\link[haven:read_spss]{haven::read_sav()}}
\item SPSS compressed (.zsav), using \code{\link[haven:read_spss]{haven::read_sav()}}.
\item Stata (.dta), using \code{\link[haven:read_dta]{haven::read_dta()}}
\item SPSS Portable Files (.por), using \code{\link[haven:read_spss]{haven::read_por()}}.
\item Excel (.xls and .xlsx), using \code{\link[readxl:read_excel]{readxl::read_xlsx()}} or \code{\link[readxl:read_excel]{readxl::read_xls()}}. Use \code{which} to specify a sheet number.
\item R syntax object (.R), using \code{\link[base:dput]{base::dget()}}
\item Saved R objects (.RData,.rda), using \code{\link[base:load]{base::load()}} for single-object .Rdata files. Use \code{which} to specify an object name for multi-object .Rdata files. This can be any R object (not just a data frame).
\item Serialized R objects (.rds), using \code{\link[base:readRDS]{base::readRDS()}}. This can be any R object (not just a data frame).
\item Serialized R objects (.qs), using \code{\link[qs:qread]{qs::qread()}}, which is
significantly faster than .rds. This can be any R
object (not just a data frame).
\item Epiinfo (.rec), using \code{\link[foreign:read.epiinfo]{foreign::read.epiinfo()}}
\item Minitab (.mtp), using \code{\link[foreign:read.mtp]{foreign::read.mtp()}}
\item Systat (.syd), using \code{\link[foreign:read.systat]{foreign::read.systat()}}
\item "XBASE" database files (.dbf), using \code{\link[foreign:read.dbf]{foreign::read.dbf()}}
\item Weka Attribute-Relation File Format (.arff), using \code{\link[foreign:read.arff]{foreign::read.arff()}}
\item Data Interchange Format (.dif), using \code{\link[utils:read.DIF]{utils::read.DIF()}}
\item Fortran data (no recognized extension), using \code{\link[utils:read.fortran]{utils::read.fortran()}}
\item Fixed-width format data (.fwf), using a faster version of \code{\link[utils:read.fwf]{utils::read.fwf()}} that requires a \code{widths} argument and by default in rio has \code{stringsAsFactors = FALSE}
\item gzip comma-separated data (.csv.gz), using \code{\link[utils:read.table]{utils::read.table()}} with \code{row.names = FALSE} and \code{stringsAsFactors = FALSE}
\item \href{https://github.com/csvy}{CSVY} (CSV with a YAML metadata header) using \code{\link[data.table:fread]{data.table::fread()}}.
\item Apache Arrow Parquet (.parquet), using \code{\link[arrow:read_parquet]{arrow::read_parquet()}}
\item Feather R/Python interchange format (.feather), using \code{\link[arrow:read_feather]{arrow::read_feather()}}
\item Fast storage (.fst), using \code{\link[fst:write_fst]{fst::read.fst()}}
\item JSON (.json), using \code{\link[jsonlite:fromJSON]{jsonlite::fromJSON()}}
\item Matlab (.mat), using \code{\link[rmatio:read.mat]{rmatio::read.mat()}}
\item EViews (.wf1), using \code{\link[hexView:readEViews]{hexView::readEViews()}}
\item OpenDocument Spreadsheet (.ods, .fods), using \code{\link[readODS:read_ods]{readODS::read_ods()}} or \code{\link[readODS:read_ods]{readODS::read_fods()}}. Use \code{which} to specify a sheet number.
\item Single-table HTML documents (.html), using \code{\link[xml2:read_xml]{xml2::read_html()}}. There is no standard HTML table and we have only tested this with HTML tables exported with this package. HTML tables will only be read correctly if the HTML file can be converted to a list via \code{\link[xml2:as_list]{xml2::as_list()}}. This import feature is not robust, especially for HTML tables in the wild. Please use a proper web scraping framework, e.g. \code{rvest}.
\item Shallow XML documents (.xml), using \code{\link[xml2:read_xml]{xml2::read_xml()}}. The data structure will only be read correctly if the XML file can be converted to a list via \code{\link[xml2:as_list]{xml2::as_list()}}.
\item YAML (.yml), using \code{\link[yaml:yaml.load]{yaml::yaml.load()}}
\item Clipboard import, using \code{\link[utils:read.table]{utils::read.table()}} with \code{row.names = FALSE}
\item Google Sheets, as Comma-separated data (.csv)
\item GraphPad Prism (.pzfx) using \code{\link[pzfx:read_pzfx]{pzfx::read_pzfx()}}
}
\code{import} attempts to standardize the return value from the various import functions to the extent possible, thus providing a uniform data structure regardless of what import package or function is used. It achieves this by storing any optional variable-related attributes at the variable level (i.e., an attribute for \code{mtcars$mpg} is stored in \code{attributes(mtcars$mpg)} rather than \code{attributes(mtcars)}). If you would prefer these attributes to be stored at the data.frame-level (i.e., in \code{attributes(mtcars)}), see \code{\link[=gather_attrs]{gather_attrs()}}.
After importing metadata-rich file formats (e.g., from Stata or SPSS), it may be helpful to recode labelled variables to character or factor using \code{\link[=characterize]{characterize()}} or \code{\link[=factorize]{factorize()}} respectively.
}
\note{
For csv and txt files with row names exported from \code{\link[=export]{export()}}, it may be helpful to specify \code{row.names} as the column of the table which contain row names. See example below.
}
\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)
## specify `format` to override default format: see export()
export(iris, xlsx_file, format = "csv")
## basic
import(csv_file)
## You can certainly import your data with the file name, which is not a variable:
## import("starwars.csv"); import("mtcars.xlsx")
## Override the default format
## import(xlsx_file) # Error, it is actually not an Excel file
import(xlsx_file, format = "csv")
## import CSV as a `data.table`
import(csv_file, setclass = "data.table")
## import CSV as a tibble (or "tbl_df")
import(csv_file, setclass = "tbl_df")
## pass arguments to underlying import function
## data.table::fread is the underlying import function and `nrows` is its argument
import(csv_file, nrows = 20)
## data.table::fread has an argument `data.table` to set the class explicitely to data.table. The
## argument setclass, however, takes precedents over such undocumented features.
class(import(csv_file, setclass = "tibble", data.table = TRUE))
## the default import class can be set with options(rio.import.class = "data.table")
## option(rio.import.class = "tibble"), or option(rio.import.class = "arrow")
}
\seealso{
\code{\link[=import_list]{import_list()}}, \code{\link[=characterize]{characterize()}}, \code{\link[=gather_attrs]{gather_attrs()}}, \code{\link[=export]{export()}}, \code{\link[=convert]{convert()}}
}
rio/man/rio.Rd 0000644 0001762 0000144 00000006004 14476052611 012704 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rio.R
\docType{package}
\name{rio}
\alias{rio}
\alias{rio-package}
\title{A Swiss-Army Knife for Data I/O}
\description{
The aim of rio is to make data file input and output as easy as possible. \code{\link[=export]{export()}} and \code{\link[=import]{import()}} serve as a Swiss-army knife for painless data I/O for data from almost any file format by inferring the data structure from the file extension, natively reading web-based data sources, setting reasonable defaults for import and export, and relying on efficient data import and export packages. An additional convenience function, \code{\link[=convert]{convert()}}, provides a simple method for converting between file types.
Note that some of rio's functionality is provided by \sQuote{Suggests} dependendencies, meaning they are not installed by default. Use \code{\link[=install_formats]{install_formats()}} to make sure these packages are available for use.
}
\examples{
# export
library("datasets")
export(mtcars, csv_file <- tempfile(fileext = ".csv")) # comma-separated values
export(mtcars, rds_file <- tempfile(fileext = ".rds")) # R serialized
export(mtcars, sav_file <- tempfile(fileext = ".sav")) # SPSS
# import
x <- import(csv_file)
y <- import(rds_file)
z <- import(sav_file)
# convert sav (SPSS) to dta (Stata)
convert(sav_file, dta_file <- tempfile(fileext = ".dta"))
# cleanup
unlink(c(csv_file, rds_file, sav_file, dta_file))
}
\references{
\href{https://github.com/Stan125/GREA}{GREA} provides an RStudio add-in to import data using rio.
}
\seealso{
\code{\link[=import]{import()}}, \code{\link[=import_list]{import_list()}}, \code{\link[=export]{export()}}, \code{\link[=export_list]{export_list()}}, \code{\link[=convert]{convert()}}, \code{\link[=install_formats]{install_formats()}}
}
\author{
\strong{Maintainer}: Chung-hong Chan \email{chainsawtiney@gmail.com} (\href{https://orcid.org/0000-0002-6232-7530}{ORCID})
Authors:
\itemize{
\item Jason Becker \email{jason@jbecker.co}
\item David Schoch \email{david@schochastics.net} (\href{https://orcid.org/0000-0003-2952-4812}{ORCID})
\item Thomas J. Leeper \email{thosjleeper@gmail.com} (\href{https://orcid.org/0000-0003-4097-6326}{ORCID})
}
Other contributors:
\itemize{
\item Geoffrey CH Chan \email{gefchchan@gmail.com} [contributor]
\item Christopher Gandrud [contributor]
\item Andrew MacDonald [contributor]
\item Ista Zahn [contributor]
\item Stanislaus Stadlmann [contributor]
\item Ruaridh Williamson \email{ruaridh.williamson@gmail.com} [contributor]
\item Patrick Kennedy [contributor]
\item Ryan Price \email{ryapric@gmail.com} [contributor]
\item Trevor L Davis \email{trevor.l.davis@gmail.com} [contributor]
\item Nathan Day \email{nathancday@gmail.com} [contributor]
\item Bill Denney \email{wdenney@humanpredictions.com} (\href{https://orcid.org/0000-0002-5759-428X}{ORCID}) [contributor]
\item Alex Bokov \email{alex.bokov@gmail.com} (\href{https://orcid.org/0000-0002-0511-9815}{ORCID}) [contributor]
}
}
rio/man/import_list.Rd 0000644 0001762 0000144 00000006002 14502270161 014446 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/import_list.R
\name{import_list}
\alias{import_list}
\title{Import list of data frames}
\usage{
import_list(
file,
setclass = getOption("rio.import.class", "data.frame"),
which,
rbind = FALSE,
rbind_label = "_file",
rbind_fill = TRUE,
...
)
}
\arguments{
\item{file}{A character string containing a single file name for a multi-object file (e.g., Excel workbook, zip file, or HTML file), or a vector of file paths for multiple files to be imported.}
\item{setclass}{An optional character vector specifying one or more classes
to set on the import. By default, the return object is always a
\dQuote{data.frame}. Allowed values include \dQuote{tbl_df}, \dQuote{tbl}, or
\dQuote{tibble} (if using tibble), \dQuote{arrow}, \dQuote{arrow_table} (if using arrow table; the suggested package \code{arrow} must be installed) or \dQuote{data.table} (if using
data.table). Other values are ignored, such that a data.frame is returned.
The parameter takes precedents over parameters in \dots which set a different class.}
\item{which}{If \code{file} is a single file path, this specifies which objects should be extracted (passed to \code{\link[=import]{import()}}'s \code{which} argument). Ignored otherwise.}
\item{rbind}{A logical indicating whether to pass the import list of data frames through \code{\link[data.table:rbindlist]{data.table::rbindlist()}}.}
\item{rbind_label}{If \code{rbind = TRUE}, a character string specifying the name of a column to add to the data frame indicating its source file.}
\item{rbind_fill}{If \code{rbind = TRUE}, a logical indicating whether to set the \code{fill = TRUE} (and fill missing columns with \code{NA}).}
\item{\dots}{Additional arguments passed to \code{\link[=import]{import()}}. Behavior may be unexpected if files are of different formats.}
}
\value{
If \code{rbind=FALSE} (the default), a list of a data frames. Otherwise, that list is passed to \code{\link[data.table:rbindlist]{data.table::rbindlist()}} with \code{fill = TRUE} and returns a data frame object of class set by the \code{setclass} argument; if this operation fails, the list is returned.
}
\description{
Use \code{\link[=import]{import()}} to import a list of data frames from a vector of file names or from a multi-object file (Excel workbook, .Rdata file, zipped directory in a zip file, or HTML file)
}
\examples{
## For demo, a temp. file path is created with the file extension .xlsx
xlsx_file <- tempfile(fileext = ".xlsx")
export(
list(
mtcars1 = mtcars[1:10, ],
mtcars2 = mtcars[11:20, ],
mtcars3 = mtcars[21:32, ]
),
xlsx_file
)
# import a single file from multi-object workbook
import(xlsx_file, sheet = "mtcars1")
# import all worksheets, the return value is a list
import_list(xlsx_file)
# import and rbind all worksheets, the return valye is a data frame
import_list(xlsx_file, rbind = TRUE)
}
\seealso{
\code{\link[=import]{import()}}, \code{\link[=export_list]{export_list()}}, \code{\link[=export]{export()}}
}
rio/man/install_formats.Rd 0000644 0001762 0000144 00000001336 14476051106 015315 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/suggestions.R
\name{install_formats}
\alias{install_formats}
\title{Install rio's \sQuote{Suggests} Dependencies}
\usage{
install_formats(...)
}
\arguments{
\item{\dots}{Additional arguments passed to \code{\link[utils:install.packages]{utils::install.packages()}}.}
}
\value{
\code{NULL}
}
\description{
This function installs various \sQuote{Suggests} dependencies for rio that expand its support to the full range of support import and export formats. These packages are not installed or loaded by default in order to create a slimmer and faster package build, install, and load.
}
\examples{
\donttest{
if (interactive()) {
install_formats()
}
}
}
rio/man/get_info.Rd 0000644 0001762 0000144 00000002761 14476631364 013723 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{get_info}
\alias{get_info}
\alias{get_ext}
\title{Get File Info}
\usage{
get_info(file)
get_ext(file)
}
\arguments{
\item{file}{A character string containing a filename, file path, or URL.}
}
\value{
For \code{\link[=get_info]{get_info()}}, a list is return with the following slots
\itemize{
\item \code{input} file extension or information used to identify the possible file format
\item \code{format} file format, see \code{format} argument of \code{\link[=import]{import()}}
\item \code{type} "import" (supported by default); "suggest" (supported by suggested packages, see \code{\link[=install_formats]{install_formats()}}); "enhance" and "known " are not directly supported; \code{NA} is unsupported
\item \code{format_name} name of the format
\item \code{import_function} What function is used to import this file
\item \code{export_function} What function is used to export this file
\item \code{file} \code{file}
}
For \code{\link[=get_ext]{get_ext()}}, just \code{input} (usually file extension) is returned; retained for backward compatibility.
}
\description{
A utility function to retrieve the file information of a filename, path, or URL.
}
\examples{
get_info("starwars.xlsx")
get_info("starwars.ods")
get_info("https://github.com/ropensci/readODS/raw/v2.1/starwars.ods")
get_info("~/duran_duran_rio.mp3")
get_ext("clipboard") ## "clipboard"
get_ext("https://github.com/ropensci/readODS/raw/v2.1/starwars.ods")
}
rio/man/convert.Rd 0000644 0001762 0000144 00000003411 14476051106 013570 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/convert.R
\name{convert}
\alias{convert}
\title{Convert from one file format to another}
\usage{
convert(in_file, out_file, in_opts = list(), out_opts = list())
}
\arguments{
\item{in_file}{A character string naming an input file.}
\item{out_file}{A character string naming an output file.}
\item{in_opts}{A named list of options to be passed to \code{\link[=import]{import()}}.}
\item{out_opts}{A named list of options to be passed to \code{\link[=export]{export()}}.}
}
\value{
A character string containing the name of the output file (invisibly).
}
\description{
This function constructs a data frame from a data file using \code{\link[=import]{import()}} and uses \code{\link[=export]{export()}} to write the data to disk in the format indicated by the file extension.
}
\examples{
## For demo, a temp. file path is created with the file extension .dta (Stata)
dta_file <- tempfile(fileext = ".dta")
## .csv
csv_file <- tempfile(fileext = ".csv")
## .xlsx
xlsx_file <- tempfile(fileext = ".xlsx")
## Create a Stata data file
export(mtcars, dta_file)
## convert Stata to CSV and open converted file
convert(dta_file, csv_file)
import(csv_file)
## correct an erroneous file format
export(mtcars, xlsx_file, format = "tsv") ## DON'T DO THIS
## import(xlsx_file) ## ERROR
## convert the file by specifying `in_opts`
convert(xlsx_file, xlsx_file, in_opts = list(format = "tsv"))
import(xlsx_file)
## convert from the command line:
## Rscript -e "rio::convert('mtcars.dta', 'mtcars.csv')"
}
\seealso{
\href{https://lbraglia.github.io/}{Luca Braglia} has created a Shiny app called \href{https://github.com/lbraglia/rioweb}{rioweb} that provides access to the file conversion features of rio through a web browser.
}
rio/man/gather_attrs.Rd 0000644 0001762 0000144 00000002276 14500666516 014614 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/gather_attrs.R
\name{gather_attrs}
\alias{gather_attrs}
\alias{spread_attrs}
\title{Gather attributes from data frame variables}
\usage{
gather_attrs(x)
spread_attrs(x)
}
\arguments{
\item{x}{A data frame.}
}
\value{
\code{x}, with variable-level attributes stored at the data frame level.
}
\description{
\code{gather_attrs} moves variable-level attributes to the data frame level and \code{spread_attrs} reverses that operation.
}
\details{
\code{\link[=import]{import()}} attempts to standardize the return value from the various import functions to the extent possible, thus providing a uniform data structure regardless of what import package or function is used. It achieves this by storing any optional variable-related attributes at the variable level (i.e., an attribute for \code{mtcars$mpg} is stored in \code{attributes(mtcars$mpg)} rather than \code{attributes(mtcars)}). \code{gather_attrs} moves these to the data frame level (i.e., in \code{attributes(mtcars)}). \code{spread_attrs} moves attributes back to the variable level.
}
\seealso{
\code{\link[=import]{import()}}, \code{\link[=characterize]{characterize()}}
}
rio/man/characterize.Rd 0000644 0001762 0000144 00000003575 14476051106 014567 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/characterize.R
\name{characterize}
\alias{characterize}
\alias{factorize}
\alias{characterize.default}
\alias{characterize.data.frame}
\alias{factorize.default}
\alias{factorize.data.frame}
\title{Character conversion of labelled data}
\usage{
characterize(x, ...)
factorize(x, ...)
\method{characterize}{default}(x, ...)
\method{characterize}{data.frame}(x, ...)
\method{factorize}{default}(x, coerce_character = FALSE, ...)
\method{factorize}{data.frame}(x, ...)
}
\arguments{
\item{x}{A vector or data frame.}
\item{\dots}{additional arguments passed to methods}
\item{coerce_character}{A logical indicating whether to additionally coerce character columns to factor (in \code{factorize}). Default \code{FALSE}.}
}
\value{
a character vector (for \code{characterize}) or factor vector (for \code{factorize})
}
\description{
Convert labelled variables to character or factor
}
\details{
\code{characterize} converts a vector with a \code{labels} attribute of named levels into a character vector. \code{factorize} does the same but to factors. This can be useful at two stages of a data workflow: (1) importing labelled data from metadata-rich file formats (e.g., Stata or SPSS), and (2) exporting such data to plain text files (e.g., CSV) in a way that preserves information.
}
\examples{
## vector method
x <- structure(1:4, labels = c("A" = 1, "B" = 2, "C" = 3))
characterize(x)
factorize(x)
## data frame method
x <- data.frame(v1 = structure(1:4, labels = c("A" = 1, "B" = 2, "C" = 3)),
v2 = structure(c(1,0,0,1), labels = c("foo" = 0, "bar" = 1)))
str(factorize(x))
str(characterize(x))
## Application
csv_file <- tempfile(fileext = ".csv")
## comparison of exported file contents
import(export(x, csv_file))
import(export(factorize(x), csv_file))
}
\seealso{
\code{\link[=gather_attrs]{gather_attrs()}}
}
rio/man/figures/ 0000755 0001762 0000144 00000000000 14500616167 013270 5 ustar ligges users rio/man/figures/logo.png 0000644 0001762 0000144 00000123701 14500615377 014744 0 ustar ligges users PNG
IHDR pHYs M M=@ tEXtSoftware www.inkscape.org< IDATxwTߙuVҋHJS(Es
&1h,WBrMDI4
H
* ".l϶i|.3Ϝ}"{( Lrl LU2(AAPTC:&η@B j&zN-ڋT"XAAPXҷsA%\¶ܵ kqLl3_