box_read: Read an R object from a Box file

Description

These functions are used to download a Box file, specified by file_id, then attempt to parse its contents into memory as an R object. For example, you may wish to read a Box CSV file as a data.frame.

Usage

box_read(
  file_id,
  type = NULL,
  version_id = NULL,
  version_no = NULL,
  read_fun = rio::import,
  ...
)
box_read_csv(file_id, ...)
box_read_tsv(file_id, ...)
box_read_json(file_id, ...)
box_read_excel(file_id, ...)
box_read_rds(file_id, ...)

Arguments

file_id

numeric or character, file ID at Box.

type

character, MIME type used to override the content type returned by the server.

version_id

character or numeric, the version_id of the file.

version_no

numeric, version of the file you'd like to download (starting at 1).

read_fun

function, used to read (parse) the content into R; for box_read() the default function is rio::import(); the specific helpers each use a different function directly.

...

Other arguments passed to read_fun.

Value

Object returned by function read_fun.

rio's import() and JSON files

In rio (0.5.18) there was a change in how JSON files are processed by rio::import(), a non-data.frame object stored in JSON is no longer coerced into a data.frame. The old behavior would produce unexpected results or fatal errors if the stored object was not a data.frame. The new behavior is closer to that of the underlying function jsonlite::fromJSON() and similar to the behavior for RDS files.

In keeping with the spirit of jsonlite, box_read_json() has been modified to call jsonlite::fromJSON() directly, which by-passes the old "undesirable" behavior of rio (< 0.5.18). If you are using the current CRAN release of rio (0.5.16) you should use jsonlite::read_json() to avoid these issues.

Details

This is a two-step process. The first is to download the contents of the file, the second is to parse those contents into an R object. The default parsing-function is rio::import().

In addition to box_read(), some specific helpers are provided:

box_read_csv(): parse a remote CSV file into a data.frame. Default read-function is rio::import() with format = "csv", which uses data.table::fread() if available, and utils::read.csv() if not. Pass the argument fread = FALSE to ... to always use utils::read.csv().
box_read_tsv(): parse a remote TSV file into a data.frame. Default read-function is rio::import() with format = "tsv", which uses data.table::fread() if available, and utils::read.delim() if not. Pass the argument fread = FALSE to ... to always use utils::read.delim().
box_read_json(): parse a remote JSON file into a R object. Default read-function is jsonlite::fromJSON().
box_read_excel(): parse a remote Microsoft Excel file into a data.frame. Default read-function is rio::import() with format = "excel", which uses readxl::read_excel() by default. Pass the argument readxl = FALSE to ... to use openxlsx::read.xlsx() instead.
box_read_rds(): parse an RDS file into a R object. Uses readRDS().