R/create_env_nsets.R

In charliem2003/sdmProfiling: A Spatially-explicit Species Distribution Model Evaluation Tool

################################################################################
### create_env_nsets
### 01/2022

#' Generate multiple sets of related environmental variables.
#'
#' @description Essentially a wrapper around \code{\link{create_env_set}}. Each
#'  set of environmental variables (can be just 1 variable) that are related
#'  but have some random variation between them. The first variable is
#'  generated using unconditional Gaussian simulation using a variogram model
#'  with the specified model and psill parameter, using
#'  \code{\link[gstat]{vgm}} from the \code{gstat} package, plus a random
#'  range value extracted using the specified distribution. New conditional
#'  Gaussian simulations are then made for subsequent variables using a random
#'  subsample of cells from the first variable plus a new random range value.
#'  Each set starts from a newly generated base variables.
#'
#' @details The model and psill are kept constant across all variables, but a
#'  new range value is drawn from the specified distribution each time. The
#'  distribution is specified using a user-generated function. The user can
#'  either input the name of the function or define the function as the
#'  argument.
#'
#'  Subsequent variables are generated based on a random sample of the 1st
#'  variable. The number of cells selected is defined by \code{propsamp}; the
#'  larger the value the more similar the new variable will be to the original.
#'  The psill and model type of the variogram is kept constant across all new
#'  variables, although the psill can be altered using the parameter
#'  \code{dep1}, which is multiplied by the psill of the first variable (must
#'  be >0 and <2; default = 1).
#'
#' @author Charlie Marsh (charlie.marsh@@mailbox.org) & Yoni Gavish, based on
#'  the original code from
#'  http://santiago.begueria.es/2010/10/generating-spatially-correlated-random-fields-with-r/
#'
#' @param cellDims vector containing variable dimensions (n cell width, n cell
#'  height)
#' @param sets a vector with the number of variables for each set (generated by
#'  \code{\link{create_env_set}}). Each set is generated from a new randomly
#'  generated base environmental variable.
#' @param model model for variogram; default = "Sph" (see
#'  \code{\link[gstat]{vgm}} for options)
#' @param psill (partial) sill of the variogram model; default = 1.5 (see
#'  \code{\link[gstat]{vgm}} for options)
#' @param rangeFun name of function, or specified function, to generate random
#'  number for the range parameter of the variogram model.
#'  E.g. function() exp(runif(1, 1, 6))
#' @param propSamp proportion of cells to sample for each submodel (default =
#'  0.5)
#' @param dep1 multiplied by the psill in submodels (default = 1)
#'
#' @return A raster stack of environmental variables. For each variable all
#'  values are standardised between 0 and 1. The name of each raster relates to
#'  the number of the variable set, and then the number of the variable within
#'  that set.
#'
#' @references Variations on this method have been used to generate virtual
#'  species in:
#'
#' Gavish, Y., Marsh, C.J., Kuemmerlen, M., Stoll, S., Haase, P., Kunin, W.E.,
#'  2017. Accounting for biotic interactions through alpha-diversity
#'  constraints in stacked species distribution models. Methods in Ecology and
#'  Evolution 8, 1092–1102. https://doi.org/10.1111/2041-210X.12731
#'
#' Marsh, C.J., Gavish, Y., Kunin, W.E., Brummitt, N.A., 2019. Mind the gap:
#'  Can downscaling Area of Occupancy overcome sampling gaps when assessing
#'  IUCN Red List status? Diversity and Distributions 025, 1832–1845.
#'  https://doi.org/10.1111/ddi.12983
#'
#' @examples
#'
#' ### generate 3 sets of related variables.
#' ### set1 = 4 variables; set 2 = 3 variables; set 3 = 1 variable
#'
#' # the sampling distribution for range can either be a saved function
#' vrangeFun <- function() exp(runif(1, 1, 6))
#'
#' envSet <- create_env_nsets(cellDims = c(100, 100),
#'                            sets     = c(4, 3, 1),
#'                            model    = "Sph",
#'                            psill    = 1.5,
#'                            dep1     = 1,
#'                            rangeFun = vrangeFun,
#'                            propSamp = 0.25)
#'
#' # or we can define the function within the argument itself
#' envSet <- create_env_nsets(cellDims = c(100, 100),
#'                            sets     = c(4, 3, 1),
#'                            model    = "Sph",
#'                            psill    = 1.5,
#'                            dep1     = 1,
#'                            rangeFun = function() 100 + runif(1, -100, 100),
#'                            propSamp = 0.05)
#'
#' # the output is a raster stack which can be plotted
#' plot(envSet)
#'
################################################################################

#' @export
#' @importFrom raster stack
create_env_nsets <- function(cellDims = c(100, 100),
                             sets     = c(5, 4, 3, 1),
                             model    = "Sph",
                             psill    = 1.5,
                             dep1     = 1,
                             rangeFun = "vrangeFun",
                             propSamp = 0.25) {
  allSets <- list()
  for(set in 1:length(sets)) {
    print(paste0("Generating environmental variable set ", set,
                 ": ", sets[set], " variables"))
    envSet <- create_env_set(cellDims = cellDims,
                             nPerSet  = sets[set],
                             model    = model,
                             psill    = psill,
                             dep1     = dep1,
                             rangeFun = rangeFun,
                             propSamp = propSamp)

    ### rename
    names(envSet) <- paste0("var_", set, ".", 1:sets[set])
    allSets[[set]] <- envSet
  }

  ### stack and return
  allSets <- stack(allSets)
  return(allSets)
}