downloadFile: A wrapper around a set of downloading functions
In PredictiveEcology/reproducible: Enhance Reproducibility of R Code

downloadFile

R Documentation

A wrapper around a set of downloading functions

Description

Currently, this only deals with googledrive::drive_download, and utils::download.file(). In general, this is not intended for use by a user.

Usage

downloadFile(
  archive,
  targetFile,
  neededFiles,
  destinationPath = getOption("reproducible.destinationPath", "."),
  quick,
  checksumFile,
  dlFun = NULL,
  checkSums,
  url,
  needChecksums,
  preDigest,
  overwrite = getOption("reproducible.overwrite", TRUE),
  alsoExtract = "similar",
  verbose = getOption("reproducible.verbose", 1),
  purge = FALSE,
  .tempPath,
  ...
)

Arguments

`archive`	Optional character string giving the path of an archive containing `targetFile`, or a vector giving a set of nested archives (e.g., `c("xxx.tar", "inner.zip", "inner.rar")`). If there is/are (an) inner archive(s), but they are unknown, the function will try all until it finds the `targetFile`. See table in `preProcess()`. If it is `NA`, then it will not attempt to see it as an archive, even if it has archive-like file extension (e.g., `.zip`). This may be useful when an R function is expecting an archive directly.
`targetFile`	Character string giving the filename (without relative or absolute path) to the eventual file (raster, shapefile, csv, etc.) after downloading and extracting from a zip or tar archive. This is the file before it is passed to `postProcess`. The internal checksumming does not checksum the file after it is `postProcess`ed (e.g., cropped/reprojected/masked). Using `Cache` around `prepInputs` will do a sufficient job in these cases. See table in `preProcess()`.
`neededFiles`	Character string giving the name of the file(s) to be extracted.
`destinationPath`	Character string of a directory in which to download and save the file that comes from `url` and is also where the function will look for `archive` or `targetFile`. NOTE (still experimental): To prevent repeated downloads in different locations, the user can also set `options("reproducible.inputPaths")` to one or more local file paths to search for the file before attempting to download. Default for that option is `NULL` meaning do not search locally.
`quick`	Logical. This is passed internally to `Checksums()` (the quickCheck argument), and to `Cache()` (the quick argument). This results in faster, though less robust checking of inputs. See the respective functions.
`checksumFile`	A character string indicating the absolute path to the `CHECKSUMS.txt` file.
`dlFun`	Optional "download function" name, such as `"raster::getData"`, which does custom downloading, in addition to loading into R. Still experimental.
`checkSums`	A checksums file, e.g., created by Checksums(..., write = TRUE)
`url`	Optional character string indicating the URL to download from. If not specified, then no download will be attempted. If not entry exists in the `CHECKSUMS.txt` (in `destinationPath`), an entry will be created or appended to. This `CHECKSUMS.txt` entry will be used in subsequent calls to `prepInputs` or `preProcess`, comparing the file on hand with the ad hoc `CHECKSUMS.txt`. See table in `preProcess()`.
`needChecksums`	A numeric, with `0` indicating do not write a new checksums, `1` write a new one, `2` append new information to existing one.
`preDigest`	The list of `preDigest` that comes from `CacheDigest` of an object
`overwrite`	Logical. Should downloading and all the other actions occur even if they pass the checksums or the files are all there.
`alsoExtract`	Optional character string naming files other than `targetFile` that must be extracted from the `archive`. If `NULL`, the default, then it will extract all files. Other options: `"similar"` will extract all files with the same filename without file extension as `targetFile`. `NA` will extract nothing other than `targetFile`. A character string of specific file names will cause only those to be extracted. See table in `preProcess()`.
`verbose`	Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., `⁠options('reproducible.verbose' = 0) to reduce to minimal⁠`
`purge`	Logical or Integer. `0/FALSE` (default) keeps existing `CHECKSUMS.txt` file and `prepInputs` will write or append to it. `1/TRUE` will deleted the entire `CHECKSUMS.txt` file. Other options, see details.
`.tempPath`	Optional temporary path for internal file intermediate steps. Will be cleared on.exit from this function.
`...`	Passed to `dlFun`. Still experimental. Can be e.g., `type` for google docs.

Value

This function is called for its side effects, which will be a downloaded file (targetFile), placed in destinationPath. This file will be checksummed, and that checksum will be appended to the checksumFile.