R/result_description.R

In manubio13/ku.enm: Detailed development of ecological niche models using Maxent

#' Helper function to describe results from complex functions
#'
#' @param process (character) name of the function which results derive from.
#' Options include: "kuenm_projchanges", "kuenm_modvar", "kuenm_hierpart",
#' "kuenm_mmop", and "kuenm_mopagree".
#' @param result.table (data.frame) data.frame with the description of results.
#' Only used when \code{process} = "kuenm_projchanges" or "kuenm_mopagree".
#' Default = NULL.
#' @param out.dir (character) name of the output directory where description
#' file will be written.
#'
#' @export
#'
#' @usage
#' result_description(process, result.table = NULL, out.dir)

result_description <- function(process, result.table = NULL, out.dir) {

  if (missing(process)) {
    stop("Argument 'process' must be defined")
  }
  if (missing(out.dir)) {
    stop("Argument 'out.dir' must be defined")
  }
  if (!dir.exists(out.dir)) {
    stop("'out.dir' does not exist")
  }

  filenam <- paste0(out.dir, "/Result_description (", process,").txt")

  if (file.exists(filenam)) {
    unlink(filenam)
  }

  # Description of results of detecting changes in projections
  if (process == "kuenm_projchanges"){
    if (is.null(result.table)) {
      stop("Argument 'result.table' must be defined")
    }

    cat("Description of results generated by the function kuenm_projchanges\n\n
  A folder or folders named starting with 'Changes' contain all results per extrapolation type.
  Each folder contains subfolders per each period of projection. Inside period-folders,
  subfolders per each scenario of projection can be found.\n\n
  Inside each scenario-folder you will find:\n
    - A folder (Binary) containing all binarized (thresholded) models.\n
    - A raster file with the comparison of continuous median models of current and projection
      periods. Name = continuous_comparison.\n
    - A raster file with the comparison of binary models considering agreement among distinct GCMs if
      more than one of them where used. Name: binary_comparison.\n\n
  Description of values in rasters resulted from comparisons:\n
    - Continuous comparison generally ranges from -1 to 1. Although the range may vary, negative
      values represent decrease in suitability and positive values represent increase; values
      close to zero represent more stability.\n
    - The table below indicates what each value in binary comparison represents.\n\n", file = filenam)

    suppressWarnings(
      write.table(result.table, filenam, sep = "\t", append = TRUE,
                  quote = FALSE, row.names = FALSE)
    )
  }

  # Description of results of creating maps of variance
  if (process == "kuenm_modvar"){
    cat("Description of results generated by the function kuenm_modvar\n\n
  A folder or folders named starting with 'Variation' contain all results per extrapolation
  type. Each folder contains subfolders per each area of projection. Inside these subfolders,
  a raster file for each source of variation will be found.\n
  Values in these raster files represent the variance coming from each source of
  variation. These values start from zero and are comparable among distinct sources
  of variation.\n\n
  Using a continuous color scale to plot maps is recommended.", file = filenam)
  }

  # Description of results of hierarchical partitioning analyses
  if (process == "kuenm_hierpart"){
    cat("Description of results generated by the function kuenm_hierpart\n\n
  A folder or folders named starting with 'HP_results' contain all results per extrapolation type.
  Each folder contains subfolders per each area/time of projection in which more than
  one source of variation is considered. Per each area of projection, a folder contains
  csv files with the numerical results of hierarchical partitioning analyses. If the
  argument keep.tables was defined as TRUE, an additional folder containing csv files
  with all sampled data per each iteration can be found. A bar-plot summarizing the
  total effects of each source of variation on the overall variance can also be found
  in each HP_results folder.\n\n
  Description of csv files resulted from hierarchical partitioning analyses:\n
    - hierpart_Goodness_fit.csv contains values that represent how well the satistical
      model fitted the data.\n
    - hierpart_Raw_effects.csv contains values of Independent, Joint, and Total effects
      for all iterations of the hierarchical partitioning analysis.\n
    - hierpart_Mean_effects.csv contains mean values of Independent, Joint, and Total
      effects from all iterations.\n
    - hierpart_Total_effects_percent.csv contains values of total effects for all
      iterations, expressed as percentages. These values are used to create the bar-plot.\n", file = filenam)
  }

  # Description of results of MOP analyses for multiple layers
  if (process == "kuenm_mmop"){
    cat("Description of results generated by the function kuenm_mmop\n\n
  A folder or folders named as the sets of variables analyzed contain all results of
  extrapolation risk analyses using the MOP metric.\n\n
  Inside each set-folder, raster files resulted from MOP analyses can be found. The names
  of the raster layers will help to identify the specific time period, emission scenario,
  and/or general circulation model accordingly.\n\n
  Values in raster files range from zero to one, where zero represents strict extrapolative
  areas, and other values represent levels of similarity between the calibration area and
  the specific scenario of projection. Suitability in areas of strict extrapolation
  (values of zero), should be interpreted carefully.\n\n
  Representing strict extrapolative areas separate from areas with distinct levels of
  similarity is recommended. However, if multiple GCMs where used, users may find convenient to
  use the kuenm_mopagree function, which creates raster layers of strict extrapolative area
  agreement among distinct GCMs.", file = filenam)
  }

  # Description of results of agreement of extrapolative areas derived from MOP analyses
  if (process == "kuenm_mopagree"){
    if (is.null(result.table)) {
      stop("Argument 'result.table' must be defined")
    }

    cat("Description of results generated by the function kuenm_mopagree\n\n
  A folder or folders named as the sets of variables analyzed contain all results of agreement
  of strict extrapolative areas among distinct GCMs, per each emission scenario.\n\n
  Inside each set-folder, raster files resulted from exploring the agreement of strict
  extrapolative areas among GCMs can be found. The names of the raster layers will help
  to identify the specific time period and emission scenario accordingly.
  A raster layer of MOP results for the current period can also be found here.\n\n
  Values in raster files range from zero to a number equal to the number of GCMs
  used to perform model projection. The table below indicates what each value in raster
  layers of agreement represents. Values in raster layer for the current period should be
  interpreted as in layers obtained with MOP analysis.\n\n", file = filenam)

    suppressWarnings(
      write.table(result.table, filenam, sep = "\t", append = TRUE,
                  quote = FALSE, row.names = FALSE)
    )
  }
}