ellipsoid_overlap: Overlap of ellipsoid-based ecological niche models

In marlonecobos/ellipsenm: Ecological Niche's Characterizations Using Ellipsoids

Overlap of ellipsoid-based ecological niche models

Description

ellipsoid_overlap performs analyses to measure the degree of overlap between two or more ellipsoid-based ecological niches as in pairwise comparisons. Measures can be done considering the entire ellipsoid volume or sets of environmental conditions (background).

Usage

ellipsoid_overlap(..., overlap_type = "all", n_points = 1000000,
                  significance_test = FALSE, replicates = 1000,
                  confidence_limit = 0.05)

Arguments

...	data_overlap objects containing data for individual niches to be compared in overlap analyses. At least two data_overlap objects are needed to perform analyses. These objects can be created with the function overlap_object.
overlap_type	(character) type of overlap to be measured. Options are: "all", "full", and "back_union". Default = "all". See details.
n_points	(character) number of random points to be generated for performing Monte-Carlo simulations for full overlap-type measurements. Default = 1000000.
significance_test	(logical) whether or not to perform a test to determine statistical significance of overlap results. See details; default = FALSE.
replicates	(numeric) number of replicates to be performed during the significance test; default = 1000.
confidence_limit	(numeric) confidence limit for the significance test. Default = 0.05

Details

Types of overlap are as follows:

• "all", performs all types of overlap analyses allowed.

• "full", measures overlap of the complete volume of the ellipsoidal niches.

• "back_union", meausures overlap of ellipsoidal niches considering only the union of the environmental conditions relevant for the two species (backgrounds).

The statistical significance test consist in randomly sampling the background with n = to the number of records of each species and creting ellipsoids with such data. Overlap is measured for each pair of random-ellipsoids according to the overlap_type selected. The process is repeated replicate times and the observed overlap value is compared to the values found for pairs of random-ellipsoids. The null hypothesis is that the niches are overlaped and if the observed values are as exterme or more extreme than the lower limit of the values found for the random-ellipsoids, the null hypothesis is rejected. This is, if the observed overlap value is lower than the 95% (or the value defined in confidence_limit) of the random-derived values of overlap, the niches are considered not-overlapped. If the observed value cannot be distinguished from random, the null hypothesis cannot be rejected. A p-value and the pre-defined confidence_limit will be added to the overlap matrix when the test is performed. A list with all the overlap results from the analyses with random-ellipsoids will be added to the overlap_ellipsoid object returned.

Value

An object of class overlap_ellipsoid containing all results from overlap analyses as well as other information needed for plotting.

Examples

# reading data
occurrences <- read.csv(system.file("extdata", "occurrences.csv",
                                    package = "ellipsenm"))

# raster layers of environmental data
vars <- raster::stack(list.files(system.file("extdata", package = "ellipsenm"),
                                 pattern = "bio", full.names = TRUE))

# preparing data
vext <- raster::extent(vars)
ext1 <- raster::extent(vext[1], (mean(vext[1:2]) + 0.2), vext[3:4])
ext2 <- raster::extent((mean(vext[1:2]) + 0.2), vext[2], vext[3:4])

# croping variables and splitting occurrences
vars1 <- raster::stack(raster::crop(vars, ext1))
vars2 <- raster::stack(raster::crop(vars, ext2))

occurrences1 <- occurrences[occurrences$longitude < (mean(vext[1:2]) + 0.2), ]
occurrences2 <- occurrences[!occurrences$longitude %in% occurrences1$longitude, ]

# preparing overlap objects to perform analyses
niche1 <- overlap_object(occurrences1, species =  "species", longitude = "longitude",
                         latitude = "latitude", method = "covmat", level = 95,
                         variables = vars1)

niche2 <- overlap_object(occurrences2, species =  "species", longitude = "longitude",
                         latitude = "latitude", method = "covmat", level = 95,
                         variables = vars2)

# niche overlap analysis
overlap <- ellipsoid_overlap(niche1, niche2)

marlonecobos/ellipsenm documentation built on Oct. 18, 2023, 8:09 a.m.