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

# packages to load
packages <- c("ellipse", "ellipsenm", "knitr", "maps", "raster", "rgl", 
              "rmdformats", "viridis")
suppressWarnings(s <- sapply(packages, function(x) {library(x, character.only = T)}))

# global options
opts_chunk$set(echo=FALSE, cache=FALSE, prompt=FALSE, tidy=TRUE, comment=NA,
               message=FALSE, warning=FALSE, fig.align='center', webgl=hook_webgl)
opts_knit$set(width=100)

# reading data
load("enm_report_data.RData")

This is the final report produced during the execution of the function ellipsoid_model from the ellipsenm package. Following, a complete description of the ecological niche modeling process for the species r as.character(data[1, 1]) is presented. An ecological niche, from a Grinnellian perspective, is the set of environmental conditions that allow a species to maintain populations for long periods of time, without immigration events (Peterson et al. 2011). Models created with the ellipsenm package are ellipsoid envelope models and assume that a species ecological niche is convex, has an only optimum, and the species response to each variable covaries with the response to other variables (see Brown 1984, Jimenéz et al. 2019, Osorio-Olvera et al. 2019). Mahalanobis distances are used to represent how far is each combination of environmental conditions from the optimum (ellipsoid centroid). Given the type of prediction selected in the execution of the ellipsoid_model function, this report presents results for Mahalanobis distances.

Note 1: If only one replicate was performed, results are obtained using the hole set of data. If multiple replicates were performed, results are produced per replicate; as each replicate is build with a sub-sample of the data, results may differ among replicates. For replicated models, mean results are shown in this report, results for all replicates, as well as for mean, minimum, and maximum ellipsoidal models can be found in the output directory defined in the function ellipsoid_model. If the model was performed with replicates, further raster calculations can be performed to show model variability (e.g., range or other indicators of model variability; see Peterson et al. 2018)

Note 2: If more than tree dimensions were used to create the model, up to three of them will be used in graphical representations.

Tip: To see two dimensional figures in their actual size click on them. Three dimensional figures are interactive.

---

Summary

The model presented in this report was produced for the species r as.character(data[1, 1]) to measure distances from the centroid of its niche to each of the available environmental conditions in the area of interest. The modeling process was performed with r ifelse(replicates > 1, paste0(replicates, " replicates"), "1 replicate").r if (replicates > 1) {ifelse(replicate_type == "bootstrap", paste0(" Replicates were produced using bootstrapped subsamples of ", bootstrap_percentage, "% of the data.", " Replicates were produced by excluding one occurrence record at the time."))} Based on the level used to produce the ellipsoids (r as.character(mean_pred@level)) the error (E) assumed for the occurrence data was r as.character(100 - mean_pred@level)%. This is, r as.character(100 - mean_pred@level)% of the occurrence data is considered as potentially erroneous (i.e., environmental outliers); therefore, this data is not included in the ellipsoid envelope model for the species ecological niche.

Data used for modeling

A total of r nrow(data) occurrences and r n_var variables (r paste0(paste(variable_names[-length(variable_names)], collapse = ", "), ", and ", variable_names[length(variable_names)])) were used to produce the models.

Data in geographic space

The plot below shows the geographic arrangement of occurrence data on the variable r variable_names[1]. Colors correspond with values of the variable according to figure legend.

par(mar = c(2, 2, 1, 1))
raster::plot(variable1, col = viridis(255))
map(add = TRUE, col = "gray50")
points(data[, 2:3])

Data in environmental space

The plot below shows the arrangement of the occurrence data in environmental space considering r paste(ifelse(n_var > 2, "3", "2"), "dimensions").

if (n_var > 2) {
  plot3d(data[, 4:6], col = "blue3", size = 5)
  plot3d(r_values[, 1:3], col = "gray65", add = TRUE)
  rglwidget()

} else {
  par(mar = c(2, 2, 1, 1))
  plot(r_values, col = "gray65")
  points(data[, 4:5], pch = 16, col = "blue3") 
}

---

Numeric results

Numeric results of the ellipsoid envelope model for r as.character(data[1, 1]) are presented below.

Ellipsoid characteristics

The table below describes the characteristics of the ellipsoidal ecological niche model. The complete report of ellipsoids' characteristics (e.g., centroid, covariance matrix, semi-axes length, etc.) can be found in the txt files referred in the table.

kable(ell_meta, row.names = TRUE, caption = paste0("Characteristics of the ellipsoid envelope model for ", as.character(data[1, 1]), "."))

---

Predictions in environmental space

Given the data and the characteristics that define the species ellipsoidal niche (see [Data used for modeling] and [Ellipsoid characteristics]) the results in environmental space are presented bellow.

Calibration area

The calibration area is represented by the variables given to fit the ellipsoid using the ellipsoid_model function. This area is recommended to be a region that has been accessible to the species for a relevant period of time (see Barve et al. 2011). Although most methods used in the ellipsenm package are not sensible to a background (environmental conditions in the calibration area), having a well defined accessible area helps with interpretations. Bellow, a r paste(ifelse(n_var > 2, "3", "2"), "dimensional") representation of the ellipsoidal niche model and the Mahalanobis distances is shown in environmental space for the calibration area.

col1 <- rev(color_palette(nrow(r_values)))

if (n_var > 2) {
  el3d <- ellipse3d(mean_pred@covariance_matrix[1:3, 1:3],
                    centre = mean_pred@centroid[1:3], 
                    level = mean_pred@level / 100)

  ob <- new("ellipsoid", method = mean_pred@method, 
            centroid = mean_pred@centroid[1:3], 
            covariance_matrix = mean_pred@covariance_matrix[1:3, 1:3],
            level = mean_pred@level)
  suit <- predict(ob, r_values[, 1:3], "mahalanobis", TRUE)

  vals <- cbind(r_values[, 1:3], suit@mahalanobis)
  vals <- vals[order(vals[, 4], decreasing = F), 1:3]

  plot3d(data[, 4:6], col = "blue3", size = 5)
  plot3d(vals, col = col1, add = TRUE)
  wire3d(el3d, col = "darkgreen", alpha = 0.5)
  rglwidget()

} else {
  el1 <- ellipse(x = mean_pred@covariance_matrix[1:2, 1:2], 
                 centre = mean_pred@centroid[1:2], 
                 level = mean_pred@level / 100)
  xlim <- range(range(el1[, 1]), range(r_values[, 1]))
  ylim <- range(range(el1[, 2]), range(r_values[, 2])) 

  ob <- new("ellipsoid", method = mean_pred@method, 
            centroid = mean_pred@centroid[1:2], 
            covariance_matrix = mean_pred@covariance_matrix[1:2, 1:2],
            level = mean_pred@level)
  suit <- predict(ob, r_values[, 1:2], "mahalanobis", TRUE)

  vals <- cbind(r_values[, 1:2], suit@mahalanobis)
  vals <- vals[order(vals[, 3], decreasing = F), 1:2]

  par(mar = c(4, 4, 1, 1))
  plot(vals, col = col1, xlim = xlim, ylim = ylim, 
       xlab = variable_names[1], ylab = variable_names[2])
  points(data[, 4:5], pch = 19, col = "blue3") 
  lines(el1, col = "darkgreen", lwd = 1.5)
}

---

Predictions in geographic space

Given the data and the characteristics that define the species ellipsoidal niche (see [Data used for modeling] and [Ellipsoid characteristics]) the results in geographic space for Mahalanobis distances are presented bellow.

Calibration area

The geographic prediction in the calibration area is presented below. Colors correspond with values of Mahalanobis distances according to figure legend.

par(mar = c(2, 2, 1, 1))
raster::plot(layer, col = rev(color_palette(255)))
map(add = TRUE, col = "gray50")

---

This report was produced using the ellipsenm R package; to cite R and this package use the following code:

# R reference:  
citation()

# ellipsenm reference: `
citation("ellipsenm")

The code for producing this report (if needed) can be found in the file enm_mahalanobis_report.Rmd; the data used is in enm_report_data.RData.

---

References

• Barve, N., Barve, V., Jiménez-Valverde, A., Lira-Noriega, A., Maher, S.P., Peterson, A.T., Soberón, J., Villalobos, F., 2011. The crucial role of the accessible area in ecological niche modeling and species distribution modeling. Ecol. Modell. 222, 1810–1819.
• Brown, J.H., 1984. On the relationship between abundance and distribution of a species. Am. Nat. 124, 255–279.
• Jiménez, L., Soberón, J., Christen, J.A., Soto, D., 2019. On the problem of modeling a fundamental niche from occurrence data. Ecol. Modell. 397, 74–83.
• Osorio‐Olvera, L., Soberón, J., Falconi, M., 2019. On population abundance and niche structure. Ecography 42. https://doi.org/10.1111/ecog.04442.
• Peterson, A.T., Cobos, M.E., Jiménez‐García, D., 2018. Major challenges for correlational ecological niche model projections to future climate conditions. Ann. N. Y. Acad. Sci. 1429, 66–77.
• Peterson, A.T., Soberón, J., Pearson, R.G., Anderson, R.P., Martínez-Meyer, E., Nakamura, M., Araújo, M.B., 2011. Ecological Niches and Geographic Distributions. Princeton University Press, Princeton.

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