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). Suitability values result by default from a multivariate normal transformation of Mahalanobis distances. Therefore, maximum values of suitability will be close to the centroid and minimum values will be close to the border of the ellipsoid. To obtain binary layers from the ones written in the output_directory for suitability predictions, reclassify the values in the layers as follows: 0 = 0 (non-suitable, outside ellipsoid), and values other than 0 = 1 (suitable, inside ellipsoid).

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., suitability range or other indicators of model variability; see Peterson et al. 2018)

Note 2: Given the type of prediction selected in the function ellipsoid model, results for both suitability values and Mahalanobis distances are presented in this report.

Note 3: This is the report for a model projected into scenarios other than the one used for calibration. Therefore, other results correspondent to predictions for each of the projection scenarios were created in the output directory defined in the function ellipsoid_model. This report includes graphical and numeric results for only one of these projections (generally the first of all projections if multiple, or the only projection if a single one was performed). The reason for presenting only one projection is the prevention of RAM-related issues.

Note 4: 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 characterize its ecological niche using an approach based in ellipsoid envelopes. 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.

This model was projected to r length(scenarios) scenario(s). The results for all projections can be found in the output directory defined in the function ellipsoid_model under the name(s): r if (length(scenarios) > 1) {paste0(paste(scenarios[-length(scenarios)], collapse = ", "), ", and ", scenarios[length(scenarios)])} else {as.character(scenarios[1])}. Graphical and numerical results are presented only for the r as.character(scenarios[1]) scenario.

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

Calibration area

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

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

Projection scenario

Below a plot is showing the arrangement of the occurrence data in environmental space considering r paste(ifelse(n_var > 2, "3", "2"), "dimensions") for the r as.character(scenarios[1]) scenario.

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

} else {
  par(mar = c(2, 2, 1, 1))
  plot(pr_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]), "."))

Prevalence

Prevalence in environmental and geographic space are summarized below. Prevalence is defined as the proportion of space identified to be suitable for the species. The difference between the two types of prevalence is that in geographic space proportions are calculated using all pixes from the raster; whereas, in environmental space, only pixels that have distinct combinations of all variable's values are considered (see Hutchinson’s duality in Colwell and Rangel 2009).

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

Prevalence in projection scenario

Prevalence for the r as.character(scenarios[1]) scenario are presented below (if more than one projection was performed, prevalence in other scenarios can be found in the output directory).

kable(prevalences_p, row.names = TRUE, caption = paste0("Prevalence of the ellipsoid envelope model for ", as.character(data[1, 1]), " in a projection scenario."))

---

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 suitability values is shown in environmental space for the calibration area.

col1 <- 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], "both", TRUE)

  vals <- cbind(r_values[, 1:3], suit@suitability)
  vals <- vals[order(vals[, 4], decreasing = F), ]
  vals1 <- vals[vals[, 4] > 0, -4]
  vals0 <- vals[vals[, 4] == 0, -4]

  plot3d(data[, 4:6], col = "blue3", size = 5)
  plot3d(vals1, col = col1[vals[, 4] > 0], add = TRUE)
  plot3d(vals0, col = col1[1], 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], "both", TRUE)

  vals <- cbind(r_values[, 1:2], suit@suitability)
  vals <- vals[order(vals[, 3], decreasing = F), ]
  vals1 <- vals[vals[, 3] > 0, -3]
  vals0 <- vals[vals[, 3] == 0, -3]

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

A r paste(ifelse(n_var > 2, "3", "2"), "dimensional") representation of the ellipsoidal niche model and the Mahalanobis distances for the calibration area is shown in the following figure.

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)

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

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

Projection scenario

Following, a r paste(ifelse(n_var > 2, "3", "2"), "dimensional") representation of the ellipsoidal niche model and the suitability values is shown in environmental space for the r as.character(scenarios[1]) scenario.

col1 <- color_palette(nrow(pr_values))

if (n_var > 2) {
  suit <- predict(ob, pr_values[, 1:3], "suitability", TRUE)

  vals <- cbind(pr_values[, 1:3], suit@suitability)
  vals <- vals[order(vals[, 4], decreasing = F), ]
  vals1 <- vals[vals[, 4] > 0, -4]
  vals0 <- vals[vals[, 4] == 0, -4]

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

} else {
  xlim <- range(range(el1[, 1]), range(pr_values[, 1]))
  ylim <- range(range(el1[, 2]), range(pr_values[, 2])) 

  suit <- predict(ob, pr_values[, 1:2], "suitability", TRUE)

  vals <- cbind(pr_values[, 1:2], suit@suitability)
  vals <- vals[order(vals[, 3], decreasing = F), ]
  vals1 <- vals[vals[, 3] > 0, -3]
  vals0 <- vals[vals[, 3] == 0, -3]

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

A r paste(ifelse(n_var > 2, "3", "2"), "dimensional") representation of the ellipsoidal niche model and the Mahalanobis distances for the r as.character(scenarios[1]) scenario is shown in the following figure.

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

if (n_var > 2) {
  suit <- predict(ob, pr_values[, 1:3], "mahalanobis", TRUE)

  vals <- cbind(pr_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 {
  xlim <- range(range(el1[, 1]), range(pr_values[, 1]))
  ylim <- range(range(el1[, 2]), range(pr_values[, 2])) 

  suit <- predict(ob, pr_values[, 1:2], "mahalanobis", TRUE)

  vals <- cbind(pr_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 are presented bellow. Values of suitability can range from 0 to 1; when the maximum is not 1, it means that there is not environmental conditions equal to the ones at the centroid of the ellipsoid. Another reason why the range of suitability can change is that a different function of suitability was used in the ellipsoid_model function. Values of zero (coldest areas) represent places with environmental values outside the ellipsoid, values other than zero represent levels of suitability.

Calibration area

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

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

A geographic prediction of Mahalanobis distances 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[[2]], col = rev(color_palette(255)))
map(add = TRUE, col = "gray50")

Projection scenario

A geographic prediction of suitability values in a projection scenario is shown below. This example corresponds to the scenario r as.character(scenarios[1]).

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

A geographic prediction of Mahalanobis distances fo the r as.character(scenarios[1]) scenario is shown below.

par(mar = c(2, 2, 1, 1))
raster::plot(layer_projection[[2]], 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_both_pr_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.
• Colwell, R.K., Rangel, T.F., 2009. Hutchinson’s duality: The once and future niche. PNAS 106, 19651–19658.
• 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.