R/download_forcis_db.R

In FRBCesab/forcis: An R Client to Access the FORCIS Database

#' Download the FORCIS database
#'
#' @description 
#' Downloads the entire FORCIS database as a collection of five `csv` files from
#' Zenodo (\url{https://zenodo.org/doi/10.5281/zenodo.7390791}). Additional 
#' files will be also downloaded.
#'
#' @param path a `character` of length 1. The folder in which the FORCIS 
#'   database will be saved. Note that a subdirectory will be created, e.g.
#'   `forcis-db/version-99/` (with `99` the version number).
#'   
#' @param version a `character` of length 1. The version number (with two 
#'   numbers, e.g. `08` instead of `8`) of the FORCIS database to use. 
#'   Default is the latest version. Note that this argument can be handle with
#'   the global option `forcis_version`. For example, if user calls
#'   `options(forcis_version = "07")`, the version `07` will be used by default
#'   for the current R session. Note that it is recommended to use the latest 
#'   version of the database.
#' 
#' @param check_for_update a `logical`. If `TRUE` (default) the function will 
#'   check if a newer version of the FORCIS database is available on Zenodo and
#'   will print an informative message. Note that this argument can be handle 
#'   with the global option `check_for_update`. For example, if user calls
#'   `options(check_for_update = FALSE)`, the message to download the latest 
#'   version will be disabled for the current R session.
#'
#' @param overwrite a `logical`. If `TRUE` it will override the downloaded 
#'   files of the FORCIS database. Default is `FALSE`.
#'
#' @param timeout an `integer`. The timeout for downloading files from Zenodo. 
#'   Default is `60`. This number can be increased for low Internet connection.
#'
#' @return No return value. The FORCIS files will be saved in the `path` folder.
#' 
#' @details
#' The FORCIS database is regularly updated. The global structure of the tables
#' doesn’t change between versions but some bugs can be fixed and new records 
#' can be added. This is why it is recommended to use the latest version of the 
#' database. The package is designed to handle the versioning of the database on
#' Zenodo and will inform the user if a new version is available each time 
#' he/she uses one of the `read_*_data()` functions.
#' 
#' For more information, please read the vignette available at
#' \url{https://frbcesab.github.io/forcis/articles/database-versions.html}.
#' 
#' @seealso [read_plankton_nets_data()] to import the FORCIS database.
#' 
#' @references 
#' Chaabane S, De Garidel-Thoron T, Giraud X, _et al._ (2023) The FORCIS 
#' database: A global census of planktonic Foraminifera from ocean waters. 
#' _Scientific Data_, 10, 354. 
#' DOI: <https://doi.org/10.1038/s41597-023-02264-2>.
#' 
#' @export
#' 
#' @examples
#' \dontrun{
#' # Attach the package ----
#' library("forcis")
#' 
#' # Folder in which the database will be saved ----
#' path_to_save_db <- "data"
#' 
#' # Download the database ----
#' download_forcis_db(path = path_to_save_db)
#' 
#' # Check the content of the folder ----
#' list.files(path_to_save_db, recursive = TRUE)
#' }

download_forcis_db <- function(path = ".", version = options()$"forcis_version",
                               check_for_update = options()$"check_for_update",
                               overwrite = FALSE, timeout = 60) {
  
  ## Check args ----
  
  check_if_character(path)
  check_version(version)
  
  
  ## Check/set version ----
  
  if (is.null(check_for_update)) {
    check_for_update <- TRUE
  }
  
  version <- set_version(version, ask = check_for_update)
  
  
  ## Create outputs directory if required ----
  
  path <- file.path(path, "forcis-db", paste0("version-", version))
  
  if (!dir.exists(path)) {
    dir.create(path, recursive = TRUE)
  }
  
  
  ## Download files from Zenodo ----
  
  forcis_meta  <- get_version_metadata(version = version)
  forcis_files <- forcis_meta$"files"
  
  for (i in seq_len(nrow(forcis_files))) {
    
    download_file(url       = forcis_files[i, "links"]$"self",
                  path      = path, 
                  file      = forcis_files[i, "key"], 
                  overwrite = overwrite, 
                  timeout   = timeout)
  }
  
  invisible(NULL)
}