R/debark.R

In iAM-AMR/sawmill: Process Queries from the CEDAR Database

#' @title
#'   Standardize column names and screen for data entry errors, or "debark" timber
#'
#' @description
#'   \code{debark()} standardizes the column names of timber for use in \code{sawmill}.
#'   It also reports the names of any missing required columns, as well as the row/column
#'   locations of any cells of an unexpected data type (i.e. a string of text in a
#'   column that is supposed to contain numeric values only), as per \code{col_data_types}.
#'   Finally, \code{debark()} adds the columns \emph{exclude_sawmill} and
#'   \emph{exclude_sawmill_reason}, to be filled in later by \code{sawmill} as it encounters
#'   unusable factors that need to be excluded from further processing steps.
#'
#'   There is no efficient way to coerce columns; this is left to import.
#'
#' @param timber_path
#'   character: the file path to the raw timber
#'
#'
#' @return
#'   A tibble of timber with standardized column names and additional columns
#'   \emph{exclude_sawmill} and \emph{exclude_sawmill_reason}. If columns are missing and/or if
#'   unexpected data types are present, a prompt and/or error message will be returned instead.
#'
#' @importFrom dplyr rename
#' @importFrom readxl read_excel
#'
#' @export

debark <- function(timber) {
  raw_timber_specs <- get_raw_timber_specs()


  # CHECK: Required Columns Exist ---------------------------------------------

  # Get the names of required columns.
  raw_timber_req_col_names <- raw_timber_specs$timber_col_name[raw_timber_specs$timber_col_required]

  # Are required columns present?
  raw_timber_req_cols_here <- raw_timber_req_col_names %in% names(timber)

  # Abort run if required columns are missing.
  if (any(!raw_timber_req_cols_here)) {
    rlang::abort(message = glue::glue("Columns '{raw_timber_req_col_names[!raw_timber_req_cols_here]}' missing or improperly named."))
  }


  # Remap Names ---------------------------------------------------------------

  timber_col_names <- raw_timber_specs$timber_col_name
  sawmill_col_names <- raw_timber_specs$sawmill_col_name

  timber_sawmill_map <- timber_col_names
  names(timber_sawmill_map) <- sawmill_col_names

  timber <- dplyr::rename(timber, dplyr::any_of(timber_sawmill_map))

  # Update 'sawmill_status'
  status <- "OK: column names standardized and screened successfully."
  timber[, "sawmill_status"] <- status

  return(timber)
}