predict: Suitability and Mahalanobis distance predictions from...

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

Suitability and Mahalanobis distance predictions from ellipsoid* objects

Description

predicts suitability or/and Mahalanobis distance based on ellipsoid* objects.

Usage

## S4 method for signature 'ellipsoid'
predict(object, projection_variables, prediction = "suitability",
        truncate = TRUE, return_numeric, tolerance = 1e-60,
        name = NULL, format, overwrite = FALSE, force_return = FALSE)

## S4 method for signature 'ellipsoid_model_rep'
predict(object, projection_variables, prediction = "suitability",
        truncate = TRUE, return_numeric, tolerance = 1e-60,
        name = NULL, format, overwrite = FALSE, force_return = FALSE,
        return_name = NULL)

Arguments

object	a fitted object of class ellipsoid*.
projection_variables	RasterStack or matrix of variables representing environmental conditions of the scenario to which object will be projected. See details.
prediction	(character) type of prediction to be made, options are: "suitability", "mahalanobis", and "both". Default = "suitability".
truncate	(logical) whether or not to truncate values of suitability based on ellipsoid limits. All values outside the ellipsoid will be zero. Default = TRUE.
return_numeric	(logical) whether or not to return values of mahalanobis distance and suitability as part of the results (it depends on the type of prediction selected). If projection_variables is a RasterStack, default = FALSE, but can be changed to TRUE; if projection_variables is a matrix, default = TRUE and cannot be changed. See details.
tolerance	the tolerance for detecting linear dependencies. Default = 1e-60.
name	(character) optional, a name for the files to be writen. When defined, raster predictions and numeric results are not returned as part of the ellipsoid* object unless force_return = TRUE. File extensions will be added as needed for writing raster and numeric results. Default = NULL. See details.
format	(charater) if name is defined, raster type to be written. See writeFormats for details and options.
overwrite	(logical) if name is defined, whether or not to overwrite an exitent file with the exact same name. Default = FALSE.
force_return	(logical) whether or not to force returning numeric and raster results as part of the ellipsoid* object when name is defined.
return_name	(character) names of the ellipsoid (part of object) for which numeric and raster results will be forced to return if name is defined. Default = NULL.

Details

Argument object must be of one of the following classes: "ellipsoid" or "ellipsoid_model_sim". The prefix "suitability" or "mahalanobis" will be added to name depending on the type of prediction defined in prediction. File type (extention) will be added to name, if defined, .csv for numeric results and any of the ones described in writeFormats depending on format.

Argument projection_variables variables can be defined either as a RasterStack or as a matrix. If a matrix is given each column represents a variable and predictions are returned only as numeric vectors. In both cases, variable names must match exactly the order and name of variables used to create object.

If projection_variables is a matrix at least one numeric result will be returned even if return numeric is set as FALSE; if return_name is defined this indicates the ellipsoid for which the numeric result will return, if not defined, the results for the first ellipsoid will return.

The only scenarios in which none of the numeric results will be returned are: if projection_variables is a RasterStack and return numeric is set as FALSE, and if name is defined and force_return is set as FALSE, even if return numeric = TRUE for ellipsoid_model_sim. However, for the latter case, if force_return is set as TRUE, raster and numeric results will be returned for the ellipsoid defined in return_name.

Value

An ellipsoid_model* with new predictions. If name is defined, csv files with numeric results and raster files with the geographic predictions will be written.

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))


# example with simple ellipsoid
# fitting an ellipsoid
ellips1 <- ellipsoid_fit(data = occurrences, longitude = "longitude",
                         latitude = "latitude", method = "covmat",
                         level = 99, raster_layers = vars)

# predicting suitability (some slots will be empty if not required)
prediction <- predict(object = ellips1, projection_variables = vars,
                      prediction = "suitability")

class(prediction)

# predicting mahalanobis distance
prediction1 <- predict(object = ellips1, projection_variables = vars,
                       prediction = "mahalanobis")


# example with replicated ellipsoid
# getting values of variables in data
occurrences1 <- cbind(occurrences[, 2:3],
                      raster::extract(vars, occurrences[, 2:3]))

# subsampling data for construction of multiple ellipsoids
subsamples <- data_subsample(data = occurrences1, replicates = 10,
                             replicate_type = "bootstrap")

# fitting ellipsoids for the 10 subsamples
ellipsoids <- lapply(subsamples, function (x) {
  ellipsoid_fit(data = x, longitude = "longitude",
                latitude = "latitude", method = "covmat",
                level = 99)
})
names(ellipsoids) <- paste0("replicate_", 1:10)

# creating an ellipsoid_model_rep object with replicates and mean, min, max
ell_rep <- new("ellipsoid_model_rep",
               ellipsoids = c(ellipsoids, mmm_ellipsoid(ellipsoids)))

# predicting suitability
prediction_rep <- predict(object = ell_rep, projection_variables = vars,
                          prediction = "suitability")

# predicting mahalanobis distance
prediction_rep <- predict(object = ell_rep, projection_variables = vars,
                          prediction = "mahalanobis")

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