R/read_plankton_nets_data.R

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

#' Read FORCIS data
#'
#' @description
#' These functions read one specific `csv` file of the FORCIS database
#' (see below) stored in the folder `path`. The function [download_forcis_db()]
#' must be used first to store locally the database.
#'
#' @param path a `character` of length 1. The folder in which the FORCIS
#'   database has been saved.
#'
#' @inheritParams download_forcis_db
#'
#' @details
#'
#' - `read_plankton_nets_data()` reads the FORCIS plankton nets data
#' - `read_pump_data()` reads the FORCIS pump data
#' - `read_cpr_north_data()` reads the FORCIS CPR North data
#' - `read_cpr_south_data()` reads the FORCIS CPR South data
#' - `read_sediment_trap_data()` reads the FORCIS sediment traps data
#'
#' @return A `tibble`. See
#'   \url{https://zenodo.org/doi/10.5281/zenodo.7390791} for a preview of the
#'   datasets.
#'
#' @seealso [download_forcis_db()] to download the complete FORCIS database.
#'
#' @name read_data
#'
#' @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)
#'
#' # Import plankton nets data ----
#' plankton_nets_data <- read_plankton_nets_data(path = path_to_save_db)
#' }

NULL


#' @rdname read_data
#' @export

read_plankton_nets_data <- function(
  path = ".",
  version = options()$"forcis_version",
  check_for_update = options()$"forcis_check_for_update"
) {
  ## Check args ----

  check_if_character(path)
  check_version(version)

  ## Check/set version ----

  version <- set_version(version, ask = FALSE)

  ## Check local database ----

  path <- file.path(path, "forcis-db", paste0("version-", version))

  if (!dir.exists(path)) {
    stop(
      "The directory '",
      path,
      "' does not exist. Please check the ",
      "argument 'path' or use the function 'download_forcis_db()'.",
      call. = FALSE
    )
  }

  ## Check file ----

  file_name <- list.files(path, pattern = plankton_net_filename())

  if (!length(file_name)) {
    stop(
      "The Plankton net dataset does not exist. Please use the function ",
      "'download_forcis_db()'.",
      call. = FALSE
    )
  }

  ## Check for update ----

  if (is.null(check_for_update)) {
    check_for_update <- TRUE
  }

  if (check_for_update) {
    if (version != get_latest_version()) {
      message(
        "A newer version of the FORCIS database is available. Use ",
        "'download_forcis_db(version = NULL)' to download it."
      )
    }
  }

  ## Read data ----

  file_name <- list.files(path, pattern = plankton_net_filename())

  data <- vroom::vroom(
    file.path(path, file_name),
    delim = ";",
    altrep = FALSE,
    show_col_types = FALSE
  )

  data <- as.data.frame(data)

  data <- add_data_type(data, "Net")

  ## Check and convert columns ----

  taxa_columns <- get_species_names(data)

  for (i in seq_len(length(taxa_columns))) {
    data[, taxa_columns[i]] <- as.numeric(data[, taxa_columns[i]])
  }

  tibble::as_tibble(data)
}