R/espace_nicheOv.R

In wallace: A Modular Platform for Reproducible Modeling of Species Niches and Distributions

# Wallace EcoMod: a flexible platform for reproducible modeling of
# species niches and distributions.
# 
# espace_nicheOv.R
# File author: Wallace EcoMod Dev Team. 2023.
# --------------------------------------------------------------------------
# This file is part of the Wallace EcoMod application
# (hereafter “Wallace”).
#
# Wallace is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License,
# or (at your option) any later version.
#
# Wallace is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Wallace. If not, see <http://www.gnu.org/licenses/>.
# --------------------------------------------------------------------------
#
#' @title espace_nicheOv Niche Overlap
#' @description Function evaluates niche overlap between the two species for
#'   which the occurrence density grid was computed
#'
#' @details
#' The niche overlap quantification is based on the occurrence densities and
#'   the densities of environmental conditions available in the background extent
#'   that are estimated in the module Occurrence Density Grid. The function
#'   computes 4 different things; Schoener's D, unfilling, stability,
#'   expansion indices (Guisan et al. 2014 TREE), and tests for niche
#'   equivalency and niche similarity.
#'
#' @param z1 ecospat niche object for species 1 from espace_occDens.
#' @param z2 ecospat niche object for species 2 from espace_occDens.
#' @param iter numeric. Number of iterations.
#' @param equivalency logical. Whether to run equivalency test. Default is FALSE.
#' @param similarity logical. Whether to run similarity test. Default is TRUE.
#' @param logger Stores all notification messages to be displayed in the Log
#'   Window of Wallace GUI. Insert the logger reactive list here for running in
#'   shiny, otherwise leave the default NULL.
#' @examples
#' \dontrun{
#' sp.name1 <- "Bassaricyon_alleni"
#' sp.name2 <- "Bassaricyon_neblina"
#' envs <- envs_userEnvs(rasPath = list.files(system.file("extdata/wc",
#'                                            package = "wallace"),
#'                       pattern = ".tif$", full.names = TRUE),
#'                       rasName = list.files(system.file("extdata/wc",
#'                                            package = "wallace"),
#'                       pattern = ".tif$", full.names = FALSE))
#'
#' occs.z1 <- read.csv(system.file("extdata/Bassaricyon_alleni.csv",
#'                     package = "wallace"))
#' occs.z2 <- read.csv(system.file("extdata/Bassaricyon_neblina.csv",
#'                     package = "wallace"))
#'
#' bgPts.z1 <- read.csv(system.file("extdata/Bassaricyon_alleni_bgPoints.csv",
#'                      package = "wallace"))
#' bgPts.z2 <- read.csv(system.file("extdata/Bassaricyon_neblina_bgPoints.csv",
#'                      package = "wallace"))
#'
#' occsExt.z1 <- raster::extract(envs, occs.z1[, c("longitude", "latitude")])
#' occsExt.z2 <- raster::extract(envs, occs.z2[, c("longitude", "latitude")])
#' bgExt.z1 <- raster::extract(envs, bgPts.z1[, c("longitude", "latitude")])
#' bgExt.z2 <- raster::extract(envs, bgPts.z2[, c("longitude", "latitude")])
#' pcaZ <- espace_pca(sp.name1, sp.name2,
#'                    occsExt.z1, occsExt.z2,
#'                    bgExt.z1, bgExt.z2)
#' occDens <- espace_occDens(sp.name1, sp.name2, pcaZ)
#' nicheOv <- espace_nicheOv(z1 = occDens[[sp.name1]],
#'                           z2 = occDens[[sp.name2]],
#'                           iter = 100, equivalency = TRUE,
#'                           similarity = TRUE)
#' }
#'
#' @return A list of 4 elements if all is set to TRUE. Elements are overlap
#'   (Schoener's D), USE (ecospat.niche.dyn.index), equiv and simil.
#' @author Jamie Kass <jamie.m.kass@@gmail.com>
#' @author Olivier Broennimann <olivier.broennimann@@unil.ch>
#' @seealso  \code{\link{espace_pca}} \code{\link{espace_occDens}}
#'   \code{\link[ecospat]{ecospat.niche.overlap}}
#'   \code{\link[ecospat]{ecospat.niche.dyn.index}}
#'   \code{\link[ecospat]{ecospat.niche.equivalency.test}}
#'   \code{\link[ecospat]{ecospat.niche.similarity.test}}
#' @export

espace_nicheOv <- function(z1, z2, iter = 100, equivalency = FALSE,
                           similarity = TRUE, logger = NULL) {
  nicheOv <- list()

  # Schoener's D
  nicheOv$overlap <- ecospat::ecospat.niche.overlap(z1, z2, cor = TRUE)


  # Unfilling, stability, expansion indices (Guisan et al. 2014 TREE)
  nicheOv$USE <- ecospat::ecospat.niche.dyn.index(z1, z2,
                                                  intersection = 0)$dynamic.index.w

  # niche tests
  if (equivalency == TRUE) {
    smartProgress(logger, message = "Calculating niche equivalency...", {
      nicheOv$equiv <- ecospat::ecospat.niche.equivalency.test(
        z1, z2, rep = 100, overlap.alternative = "higher"
      )
    })
  }

  if (similarity == TRUE) {
    smartProgress(logger, message = "Calculating niche similarity", {
      nicheOv$simil <- ecospat::ecospat.niche.similarity.test(
        z1, z2, rep = 100, overlap.alternative = "higher", rand.type = 1
      )
    })
  }

  return(nicheOv)
}