R/fwspp_submission.R

In adamdsmith/fwspp: Querying Biodiversity Databases on USFWS Properties

#' Import species occurrence records after review and export
#'  files ready for submission to FWSpecies database
#'
#' This function imports xlsx files previously exported by
#'  \code{\link{fwspp_review}} for expert review. With appropriate
#'  reviews and edits made to the xlsx documents (see Details), they are now
#'  imported and processed (i.e., cleaned based on edits made to the
#'  review file) and exported in a format amenable to incorporation
#'  into the FWSpecies database
#'  (\url{https://sites.google.com/a/fws.gov/fwspecies/home-1}).
#'
#' During review, users may modify the values for any observation from the
#'  \code{taxon_code} to \code{evidence} columns. Two columns in particular,
#'  however, will demand the most attention - \code{accept_record} and
#'  \code{taxon_code}.
#'
#' Records without adequate documentation for inclusion in the FWSpecies
#'  database should have \code{accept_record = No}. Some observations may
#'  be set to \code{accept_record = No} by default because of ambiguous
#'  or misspelled scientific names.
#'
#' Should a valid taxonomic match be found (e.g., by retrieving the
#'  appropriate \code{taxon_code} for the correct scientific name with
#'  \code{\link{fws_taxonomy}}), update the \code{taxon_code} in the
#'  spreadsheet and set \code{accept_record = ModifiedTaxonCode}. Setting
#'  \code{accept_record = ModifiedTaxonCode}
#'  means any taxonomic changes will be incorporated, and the record accepted,
#'  in the file subsequently created for submission to the FWSpecies database.
#'
#' Changes to species taxonomy (\code{taxon_code} and \code{sci_name}) will
#'  be incorporated ONLY if \code{taxon_code} is corrected and
#'  \code{accept_record = ModifiedTaxonCode}.
#'
#' Changes or additions to common names (\code{com_name}) will be accepted
#'  ONLY if \code{accept_record = ModifiedTaxonCode}, but \code{taxon_code}
#'  need not be changed for changes only to common name.
#'
#' Changes to other columns (\code{occurrence} to \code{evidence}) will be
#'  incorporated as-is so long as \code{accept_record = Yes} or
#'  \code{accept_record = ModifiedTaxonCode}.
#'
#' Records with \code{accept_record = No} are excluded.
#'
#' @param in_dir a non-empty scalar character path to directory containing
#'  xlsx files generated by \code{\link{fwspp_review}} and subsequently
#'  reviewed to correct taxon codes or reject records. The default a
#'  \code{fwspp_review} directory in the current working directory.
#' @param out_dir a non-empty character scalar of path to store an output
#'  file for each USFWS property formatted for submission to NRPC. The
#'  default is to use or create a \code{fwspp_submission} directory within
#'  the \code{in_dir}
#' @param xlsx optional character string of xlsx files, including extension,
#'  to import from \code{in_dir}. The default (NULL) is to import all xlsx
#'  files in \code{in_dir}. Non-conforming xlsx files are skipped.
#' @param overwrite logical (default \code{FALSE}); overwrite existing files
#'  with the same name?
#' @param verbose logical (default \code{TRUE}); provide detailed messaging
#'  during review processing?
#'
#' @return \code{NULL}; Exports individual Excel file(s) to \code{out_dir}
#'  for submission to the NRPC FWSpecies database
#'
#' @import openxlsx
#'
#' @export
#'
#' @examples
#' \dontrun{
#' lowcountry <- find_fws(c("romain", "santee", "ace basin", "waccamaw"))
#' lc <- fws_occ(fws = lowcountry)
#' fwspp_review(lc)
#' # Expert review of records occurs
#' fwspp_submission()
#' }

fwspp_submission <- function(in_dir = "./fwspp_review",
                             out_dir = file.path(in_dir, "fwspp_submission"),
                             xlsx = NULL, overwrite = FALSE, verbose = TRUE) {

  if (!dir.exists(in_dir)) stop("Cannot find input directory. Check path.")
  if (!dir.exists(out_dir)) {
    dir.create(out_dir)
    message("Output directory created at ", normalizePath(out_dir))
  }

  if (is.null(xlsx))
    xlsx <- list.files(path = in_dir, pattern = ".*.xlsx$", full.names = TRUE)
  else {
    if (!all(sapply(file.path(in_dir, xlsx), file.exists)))
      stop("At least one input xlsx file was not found. Check file names?")
    xlsx <- file.path(in_dir, xlsx)
  }

  all_reviews <- lapply(xlsx, import_review, verbose) %>%
    bind_rows()
  if (!is_review(all_reviews)) stop("Unknown error during review import.")

  all_reviews <- process_review(all_reviews)

  orgs <- sort(unique(pull(all_reviews, ORGNAME)))

  if (verbose)
    invisible(
      lapply(orgs, xlsx_submission, all_reviews, out_dir,
             overwrite, verbose))
  else {
    message("Exporting files for FWSpecies submission.")
    invisible(
      pbapply::pblapply(orgs, xlsx_submission, all_reviews,
                        out_dir, overwrite, verbose))
  }
}