Skip to contents

Predicts maps of establishment suitability based on MaxEnt model ('SDMmodelCV' object)

Source: R/create_MaxEnt_suitability_maps_CV.R
create_MaxEnt_suitability_maps_CV.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_CV(
  model.obj,
  model.name,
  mypath,
  create.dir = FALSE,
  env.covar.obj,
  describe.proj = NA,
  predict.fun = "mean",
  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.

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.fun

Character. The default is "mean". This is the function to be applied to combine the iterations of the model when predicting a raster output. Can be one of: min, mean, median, max, or sd (standard deviation). If multiple are desired, must be in the concatenated form: c("mean", "sd"). Should be all lowercase.

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 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 MTP threshold under the other thresholds being plotted (because MTP is usually the smallest thresh value). However, plotting the 10_percentile thresh under the MTP threshold would not function properly and the map would not render.

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_CV() (filename ending in "summary_all_iterations.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.

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:

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.

Thresh presets list:

  • BTO = Balance training omission predicted area and threshold value

  • EE = Equate entropy of thresholded and original distributions

  • ETSS = Equal training sensitivity and specificity

  • MTP = Minimum Training Presence

  • MTSS = Maximum training sensitivity plus specificity

  • ten_percentile or 10_percentile = Ten percentile training presence

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("longitude")

  • ylab("latitude")

  • labs(fill = "Suitability for SLF")

  • 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