Import
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.
import(file, format, setclass, which, ...)
file |
A character string naming a file, URL, or single-file .zip or .tar archive. |
format |
An optional character string code of file format, which can be used to override the format inferred from |
setclass |
An optional character vector specifying one or more classes to set on the import. By default, the return object is always a “data.frame”. Allowed values include “tbl_df”, “tbl”, or “tibble” (if using dplyr) or “data.table” (if using data.table). Other values are ignored, such that a data.frame is returned. |
which |
This argument is used to control import from multi-object files; as a rule |
... |
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. |
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 format is specified).
import supports the following file formats:
Comma-separated data (.csv), using fread or, if fread = FALSE, read.table with row.names = FALSE and stringsAsFactors = FALSE
Pipe-separated data (.psv), using fread or, if fread = FALSE, read.table with sep = '|', row.names = FALSE and stringsAsFactors = FALSE
Tab-separated data (.tsv), using fread or, if fread = FALSE, read.table with row.names = FALSE and stringsAsFactors = FALSE
SAS (.sas7bdat), using read_sas.
SAS XPORT (.xpt), using read_xpt or, if haven = FALSE, read.xport.
SPSS (.sav), using read_sav. If haven = FALSE, read.spss can be used.
SPSS compressed (.zsav), using read_sav.
Stata (.dta), using read_dta. If haven = FALSE, read.dta can be used.
SPSS Portable Files (.por), using read_por.
Excel (.xls and .xlsx), using read_excel. Use which to specify a sheet number. For .xlsx files, it is possible to set readxl = FALSE, so that read.xlsx can be used instead of readxl (the default).
R syntax object (.R), using dget
Saved R objects (.RData,.rda), using load for single-object .Rdata files. Use which to specify an object name for multi-object .Rdata files. This can be any R object (not just a data frame).
Serialized R objects (.rds), using readRDS. This can be any R object (not just a data frame).
Epiinfo (.rec), using read.epiinfo
Minitab (.mtp), using read.mtp
Systat (.syd), using read.systat
"XBASE" database files (.dbf), using read.dbf
Weka Attribute-Relation File Format (.arff), using read.arff
Data Interchange Format (.dif), using read.DIF
Fortran data (no recognized extension), using read.fortran
Fixed-width format data (.fwf), using a faster version of read.fwf that requires a widths argument and by default in rio has stringsAsFactors = FALSE. If readr = TRUE, import will be performed using read_fwf, where widths should be: NULL, a vector of column widths, or the output of fwf_empty, fwf_widths, or fwf_positions.
gzip comma-separated data (.csv.gz), using read.table with row.names = FALSE and stringsAsFactors = FALSE
Apache Arrow Parquet (.parquet), using read_parquet
Feather R/Python interchange format (.feather), using read_feather
Fast storage (.fst), using read.fst
JSON (.json), using fromJSON
Matlab (.mat), using read.mat
EViews (.wf1), using readEViews
OpenDocument Spreadsheet (.ods), using read_ods. Use which to specify a sheet number.
Single-table HTML documents (.html), using read_html. The data structure will only be read correctly if the HTML file can be converted to a list via as_list.
Shallow XML documents (.xml), using read_xml. The data structure will only be read correctly if the XML file can be converted to a list via as_list.
YAML (.yml), using yaml.load
Clipboard import (on Windows and Mac OS), using read.table with row.names = FALSE
Google Sheets, as Comma-separated data (.csv)
GraphPad Prism (.pzfx) using read_pzfx
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 mtcars$mpg is stored in attributes(mtcars$mpg) rather than attributes(mtcars)). If you would prefer these attributes to be stored at the data.frame-level (i.e., in attributes(mtcars)), see 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 characterize or factorize respectively.
A data frame. If setclass is used, this data frame may have additional class attribute values, such as “tibble” or “data.table”.
For csv and txt files with row names exported from export, it may be helpful to specify row.names as the column of the table which contain row names. See example below.
# create CSV to import
export(iris, "iris1.csv")
# specify `format` to override default format
export(iris, "iris.tsv", format = "csv")
stopifnot(identical(import("iris1.csv"), import("iris.tsv", format = "csv")))
# import CSV as a `data.table`
stopifnot(inherits(import("iris1.csv", setclass = "data.table"), "data.table"))
# pass arguments to underlying import function
iris1 <- import("iris1.csv")
identical(names(iris), names(iris1))
export(iris, "iris2.csv", col.names = FALSE)
iris2 <- import("iris2.csv")
identical(names(iris), names(iris2))
# set class for the response data.frame as "tbl_df" (from dplyr)
stopifnot(inherits(import("iris1.csv", setclass = "tbl_df"), "tbl_df"))
# non-data frame formats supported for RDS, Rdata, and JSON
export(list(mtcars, iris), "list.rds")
li <- import("list.rds")
identical(names(mtcars), names(li[[1]]))
# cleanup
unlink("iris.tsv")
unlink("iris1.csv")
unlink("iris2.csv")
unlink("list.rds")Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.