Skip to contents

Predicts maps of establishment suitability based on a MaxEnt model without cross-validation ('Maxent' object)

Source: R/create_MaxEnt_suitability_maps.R
create_MaxEnt_suitability_maps.Rd

This function will create a map of establishment suitability based on a MaxEnt model trained using the SDMtune R package. It will optionally create thresholded versions of these maps using thresholds given by the MaxEnt algorithm.

Usage

create_MaxEnt_suitability_maps(
  model.obj,
  model.name,
  focal.species = "L_delicatula",
  mypath,
  create.dir = FALSE,
  env.covar.obj,
  describe.proj = NA,
  predict.type = "cloglog",
  clamp.pred = TRUE,
  thresh = NA,
  map.thresh = FALSE,
  map.thresh.extra = NA,
  map.style = NA,
  summary.file = NA
)

Arguments

model.obj

A model object created by the package 'SDMtune', should be of class 'SDMmodelCV'.

model.name

Character. A string matching the name of the object set for model.obj. Exclude unnecessary phrases, such as the "_model" ending.

focal.species

Character, default is "L_delicatula". The name of the species for which the report is generated.

mypath

Character.A file path to the sub directory where the model output will be stored. Should be used with the file.path() function (i.e. with '/' instead of '\'). If this sub directory does not already exist and should be created by the function, set create.dir = TRUE. This will create a folder from the last part of the filepath in mypath.

create.dir

Logical. Should the last element of mypath create a sub directory for the model output? If TRUE, the main folder will be created for the model output. If FALSE (ie, the sub directory already exists), only the "plots" folder within the model output sub directory will be created.

env.covar.obj

A stack of rasters of environmental covariates. These covariates may be the same covariates used to train the model, or they may be temporally or spatially projected (ex, for climate change). Suitability predictions will be made based on these rasters. See details for additional formatting information.

describe.proj

Character. Is the environmental covariate raster stack in env.covar.obj projected to a different geographical space, time period, etc than the model was trained on? If yes, enter the name of the projected period or region. This ensures that plot titles and file names reflect the projected region or time period. If using multiple words, separate with an underscore.

predict.type

Character. Default is "cloglog". The type of raster output to be created from the trained model. Can be either cloglog or c("cloglog", "logistic"). Cannot only be logistic.

clamp.pred

Logical. Default is TRUE. Should clamping be performed?

thresh

Numeric or Character. Does not need to be defined if map.thresh = FALSE This may be imported manually (numeric), or may be selected from one of the thresholds for the model (character). If a preset, the specified mean threshold value for all iterations of the model is chosen. See details for a list of preset options, explanations, and other usages.

map.thresh

Logical, TRUE by default. This function determines if a thresholded suitability map will be created. If not, output will only consist of suitability maps of the type specified in predict.fun. Note threshold maps can only be created for the cloglog output from the model. If multiple values for predict.type are specified, the function will still only produce a threshold map based on the cloglog output

map.thresh.extra

Character, default is NA. This argument will plot an extra threshold underneath the main threshold layer. It must be one of the thresholds specified in thresh and must be less than or equal to the value of the other values of thresh. For example, I use this to plot the Fixed 1 cumulative threshold under the other thresholds being plotted because it is usually the one of the smallest thresh values. If this is not the case, the extra threshold will not be visible. See confusion matrix output from compute_MaxEnt_summary_statistics() to determine threshold values.

map.style

List, default is NA. This is used to apply ggplot aesthetics to the plot outputs. If specified, the given value should be a list of ggplot aesthetic options. If not, the built-in default list will be used (see details). See examples for usage.

summary.file

Data import. Does not need to be defined if map.thresh = FALSE. Should be a .csv file or data frame that contains the summary statistics output created by compute_MaxEnt_summary_statistics() (filename ending in "_summary.csv"). If an import, file path should be in the format produced by the file.path() function (i.e. with '/' instead of '\').

Value

A raster of suitability values projected to the same spatial extent as the input env.covar.obj and a corresponding .jpg figure are created. If multiple values are given for predict.fun, then one raster and jpg image will be created for each value. If map.thresh = TRUE, then the output will also include a binary raster of suitability and a .jpg image of unsuitable areas layered on top of suitability raster. This threshold of suitability is determined by the value of thresh.

Outputs can be classified by their naming:

  • rasters containing "pred_suit" are the predicted suitability rasters

  • rasters containing "thresholded" are the same suitability rasters, but with an added threshold. The name of the threshold should directly follow this phrase. If more than one threshold is used (map.thresh.extra is defined), then the name of the lower layer will additionally follow this.

  • rasters containing "mask_layer" are the binary rasters of suitability based on the threshold, which are used as masking layers in the plotting

Use caution: will overwrite previous files by default.

Details

The function requires the packages 'cli', 'ggnewscale', 'tidyverse', 'devtools', 'SDMtune', and 'terra'

The thresholding feature of this function will limit what is considered suitable using one of a list of commonly applied thresholds. These threshold values are determined by the MaxEnt algorithm. (ie, a non-thresholded map on the cloglog scale has a lower color scale limit of 0, while a thresholded map has a lower limit determined by the algorithm.)

NOTE This function will create a thresholded suitability map for a raster output using the SD function, but this map would not be meaningful because it does not illustrate cloglog suitability (while thresholds are created using the cloglog suitability metrics).

thresh and map_thresh_extra:

This can be a single numeric or preset character value. It may also be a concatenated set of numerics or presets, as in c(0.2, 0.3) or c("MTSS", "BTO"). Note that this function only uses the cloglog version of these thresholds.

Each threshold represents a preset value and a different assumption about what is considered suitable. The user should consider the implications of using each threshold and how that informs the underlying assumption of your model.

  • BTO = Balance training omission predicted area and threshold value. This threshold is the value which best balances the predicted area and the training omission rate. It is a compromise between sensitivity and specificity.

  • EE = Equate entropy of thresholded and original distributions. This threshold is the value which best equates the entropy between the original and thresholded value. Entropy is a measure of the "uniformness" of a distribution and is the situation that constrains the internal features the least.

  • ETSS = Equal training sensitivity and specificity. Equalizes the chances of missing areas of suitable distribution and assigning unsuitable distribution.

  • fixed_1 = Fixed cumulative value 1. Omits a fixed value of the bottom 1% of suitability from the training data points.

  • fixed_5 = Fixed cumulative value 5. Omits a fixed value of the bottom 5% of suitability from the training data points.

  • fixed_10 = Fixed cumulative value 10. Omits a fixed value of the bottom 10% of suitability from the training data points.

  • MTP or LPT = Minimum Training Presence. This threshold is the lowest predicted suitability value in the training presence point set.

  • MTSS = Maximum training sensitivity plus specificity. This threshold maximizes the sum of sensitivity and specificity for the training data. We use this threshold for our main analyses.

  • ten_percentile or 10_percentile = Ten percentile training presence. This excludes the lowest 10% of predicted suitability values in the training presence point set.

NOTE We do not recommend using the MTP threshold unless for a specific purpose. This threshold is that which has a 0% omission rate of training data, but can often have an artifact (as we found in our study and as Phillips 2006 found) of defining the entire study area as suitable. This renders this threshold useless for defining suitable area.

citations: Radosavljevic, A., & Anderson, R. P. (2014), Phillips et al, (2006), Liu et al, (2016), (Damus, M. (2014, May 23). Threshold rule. Online post. Google Groups: Maxent.)

env.covar.obj:

This must a SpatRaster raster stack created using terra::rast(). The stack should include the same covariates (as raster layers) that you used to train the model and the names of the variables in these layers must be the same. You can check for naming consistency using names().

map.style:

Map style default options:

  • xlab("UTM Easting")

  • ylab("UTM Northing")

  • labs(fill = paste("Suitability for ", focal.species))

  • theme_classic()

  • theme(legend_position = "bottom")

  • theme(panel.background = element_rect(fill = "lightblue2", color = "lightblue2"), legend.title = element_text(face = "bold"))

  • scale_x_continuous(expand = c(0, 0))

  • scale_y_continuous(expand = c(0, 0))

  • coord_equal()

  • scale_fill_viridis_c(option = "D", limits = c(0, 1.00), breaks = c(0, 0.25, 0.5, 0.75, 1.00), guide = guide_colorbar(frame.colour = "black", ticks.colour = "black", barwidth = 20))

Examples