Retrieve files from ResearchBox by URL

Downloads the boxes as zips and unpacks them into the repository cache (see repo_cache_dir()), so a later call for the same box reuses the files without asking ResearchBox again.

Usage

rbox_file_download(
  rb_url,
  pb = NULL,
  file_ids = "all",
  subfolders = c("type", "section"),
  cache = FALSE
)

Arguments

rb_url

a vector of ResearchBox URLs

pb

a progress bar passed from another function

file_ids

the ids of the files to download (the file_id column of rbox_files()), or "all" (the default). ResearchBox adds a data file's codebook to the download. Needs an API key.

subfolders

how the files are put into folders: "type" (the default; "Data", "Code", "Materials", ...) or "section" ("Study 1", ...). Anything other than the default needs an API key.

cache

if TRUE, keep the downloaded files in the lasting on-disk cache (see repo_cache_dir()) so later sessions reuse them, and reuse a previously cached file list for the checksums of a download without a table of contents (see rbox_files()) instead of asking ResearchBox again. If FALSE (the default), the files are kept in a temporary folder that R removes when the session ends; within the session they are reused.

Value

a data frame with one row per file (rb_url, name, file_location, size, isdir, checksum_ok, plus the file type columns of file_types), and a "failed" attribute: a data frame with rb_url, name (NA when the whole box failed) and error for each box or file that could not be retrieved. An error starting "API rate limit exhausted: " is expected to succeed when run again later.

Details

With an API key set (see rbox_token()), each box costs one API request: the download. A peer-review link's passcode is sent along. The zip holds a table of contents with each file's MD5 checksum; every file that arrives is checked against it (checksum_ok), and a file that is listed but does not arrive, or does not match its checksum, is recorded in the "failed" attribute; that box is downloaded again on the next call. The table of contents is not returned as one of the box's files.

Without a key, or when the API cannot download the box, the download is made through the box's web page, as before. That zip has no table of contents, so with a key the box's file list is then asked for (one more request, skipped with cache = TRUE when the list is already cached) to check the files; without one, or when ResearchBox refuses the file list, checksum_ok is NA. After several downloads, the web page asks for a captcha, which metacheck cannot answer; that box is then recorded as failed.

ResearchBox blocks a key for two days when the same file is downloaded 10 times in 30 days, so a box is downloaded once and then reused from the cache.

Examples

# \donttest{
if (online("researchbox.org")) {
  # kept in this session's temporary folder (cache = FALSE); the server can
  # be busy, then this says why
  files <- tryCatch(rbox_file_download("https://researchbox.org/801"),
                    error = function(e) message(conditionMessage(e)))
  if (!is.null(files)) files[, c("name", "size")]
}
#> Warning: Could not download https://researchbox.org/801: API rate limit exhausted: ResearchBox asks for a captcha before more downloads from its web page; an API key (see ?rbox_token) avoids this
#> [1] name size
#> <0 rows> (or 0-length row.names)
# }