downloadModule: Download a module from a SpaDES module GitHub repository

In SpaDES.core: Core Utilities for Developing and Running Spatially Explicit Discrete Event Models

Download a module from a SpaDES module GitHub repository

Description

Download a .zip file of the module and extract (unzip) it to a user-specified location.

Usage

downloadModule(
  name,
  path,
  version,
  repo,
  data,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE
)

## S4 method for signature 
## 'character,character,character,character,logical,logical,ANY,logical'
downloadModule(
  name,
  path,
  version,
  repo,
  data,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE
)

## S4 method for signature 
## 'character,missing,missing,missing,missing,missing,ANY,ANY'
downloadModule(name, quickCheck, overwrite)

## S4 method for signature 'character,ANY,ANY,ANY,ANY,ANY,ANY,ANY'
downloadModule(
  name,
  path,
  version,
  repo,
  data,
  quiet,
  quickCheck = FALSE,
  overwrite = FALSE
)

Arguments

name	Character string giving the module name.
path	Character string giving the location in which to save the downloaded module.
version	The module version to download. (If not specified, or NA, the most recent version will be retrieved.)
repo	GitHub repository name, specified as "username/repo". Default is "PredictiveEcology/SpaDES-modules", which is specified by the global option spades.moduleRepo. Only master/main branches can be used at this point.
data	Logical. If TRUE, then the data that is identified in the module metadata will be downloaded, if possible. Default FALSE.
quiet	Logical. This is passed to download.file (default FALSE).
quickCheck	Logical. If TRUE, then the check with local data will only use file.size instead of digest::digest. This is faster, but potentially much less robust.
overwrite	Logical. Should local module files be overwritten in case they exist? Default FALSE.

Details

Currently only works with GitHub repositories where modules are located in a modules directory in the root tree on the master branch. Module .zip files' names should contain the version number and be inside their respective module folders (see zipModule() for zip compression of modules).

Value

A list of length 2. The first element is a character vector containing a character vector of extracted files for the module. The second element is a tbl with details about the data that is relevant for the function, including whether it was downloaded or not, and whether it was renamed (because there was a local copy that had the wrong file name).

Note

downloadModule uses the GITHUB_PAT environment variable if a value is set. This alleviates 403 errors caused by too-frequent downloads. Generate a GitHub personal access token with no additional permissions at https://github.com/settings/tokens, and add this key to ‘.Renviron’ as ⁠GITHUB_PAT=<your-github-pat-here>⁠.

The default is to overwrite any existing files in the case of a conflict.

Author(s)

Alex Chubaty

See Also

zipModule() for creating module .zip folders.

SpaDES.core documentation built on June 22, 2024, 10:32 a.m.