Project a range of calibrated species distribution models onto new environment

This function allows to project a range of models built with the BIOMOD_Modeling function onto new environmental data (which can represent new areas, resolution or time scales for example).

BIOMOD_Projection(
  bm.mod,
  proj.name,
  new.env,
  new.env.xy = NULL,
  models.chosen = "all",
  metric.binary = NULL,
  metric.filter = NULL,
  build.clamping.mask = TRUE,
  nb.cpu = 1,
  seed.val = NULL,
  ...
)

Arguments

bm.mod: a BIOMOD.models.out object returned by the BIOMOD_Modeling function
proj.name: a character corresponding to the name (ID) of the projection set (a new folder will be created within the simulation folder with this name)
new.env: A matrix, data.frame or SpatRaster object containing the new explanatory variables (in columns or layers, with names matching the variables names given to the BIOMOD_FormatingData function to build bm.mod) that will be used to project the species distribution model(s)
Note that old format from raster are still supported such as RasterStack objects.
new.env.xy: (optional, default NULL)
If new.env is a matrix or a data.frame, a 2-columns matrix or data.frame containing the corresponding X and Y coordinates that will be used to project the species distribution model(s)
models.chosen: a vector containing model names to be kept, must be either all or a sub-selection of model names that can be obtained with the get_built_models function applied to bm.mod
metric.binary: (optional, default NULL)
A vector containing evaluation metric names to be used to transform prediction values into binary values based on models evaluation scores obtained with the BIOMOD_Modeling function. Must be among all (same evaluation metrics than those of bm.mod) or POD, FAR, POFD, SR, ACCURACY, BIAS, AUCroc, AUCprg, TSS, KAPPA, OR, ORSS, CSI, ETS, BOYCE, MPA
Note that this is for binary data only.
metric.filter: (optional, default NULL)
A vector containing evaluation metric names to be used to transform prediction values into filtered values based on models evaluation scores obtained with the BIOMOD_Modeling function. Must be among all (same evaluation metrics than those of bm.mod) or POD, FAR, POFD, SR, ACCURACY, BIAS, AUCroc, AUCprg, TSS, KAPPA, OR, ORSS, CSI, ETS, BOYCE, MPA
Note that this is for binary data only.
build.clamping.mask: (optional, default TRUE)
A logical value defining whether a clamping mask should be built and saved on hard drive or not (see Details)
nb.cpu: (optional, default 1)
An integer value corresponding to the number of computing resources to be used to parallelize the single models computation
seed.val: (optional, default NULL)
An integer value corresponding to the new seed value to be set
...: (optional, see Details))

Value

A BIOMOD.projection.out object containing models projections, or links to saved outputs.
Models projections are stored out of R (for memory storage reasons) in proj.name folder created in the current working directory :

the output is a data.frame if new.env is a matrix or a data.frame
it is a SpatRaster if new.env is a SpatRaster (or several SpatRaster objects, if new.env is too large)
raw projections, as well as binary and filtered projections (if asked), are saved in the proj.name folder

Details

If models.chosen = 'all', projections are done for all calibration and pseudo absences runs if applicable.
These projections may be used later by the BIOMOD_EnsembleForecasting function.

If build.clamping.mask = TRUE, a raster file will be saved within the projection folder. This mask values will correspond to the number of variables in each pixel that are out of their calibration / validation range, identifying locations where predictions are uncertain.

... can take the following values :

omit.na: (optional, default TRUE) :
a logical value defining whether all not fully referenced environmental points will get NA as predictions or not
digits: (optional, default 0) :
an integer value corresponding to the number of digits of the predictions
on_0_1000: (optional, default TRUE) :
a logical value defining whether 0 - 1 probabilities are to be converted to 0 - 1000 scale to save memory on backup
keep.in.memory: (optional, default TRUE) :
a logical value defining whether all projections are to be kept loaded at once in memory, or only links pointing to hard drive are to be returned
do.stack: (optional, default TRUE) :
a logical value defining whether all projections are to be saved as one SpatRaster object or several SpatRaster files (the default if projections are too heavy to be all loaded at once in memory)
output.format: (optional, default .RData or .tif) :
a character value corresponding to the projections saving format on hard drive, must be either .grd, .img, .tif or .RData (the default if new.env is given as matrix or data.frame)
compress: (optional, default TRUE) :
a logical or a character value defining whether and how objects should be compressed when saved on hard drive. Must be either TRUE, FALSE, gzip (for Windows OS) or xz (for other OS)
overwrite: (optional, default do.stack) :
a logical defining whether pre-existing projections with same modeling ID and project name should be replaced or not

Author

Wilfried Thuiller, Damien Georges

Examples

library(terra)

# Load species occurrences (6 species available)
data(DataSpecies)
head(DataSpecies)

# Select the name of the studied species
myRespName <- 'GuloGulo'

# Get corresponding presence/absence data
myResp <- as.numeric(DataSpecies[, myRespName])

# Get corresponding XY coordinates
myRespXY <- DataSpecies[, c('X_WGS84', 'Y_WGS84')]

# Load environmental variables extracted from BIOCLIM (bio_3, bio_4, bio_7, bio_11 & bio_12)
data(bioclim_current)
myExpl <- terra::rast(bioclim_current)

DONTSHOW({
myExtent <- terra::ext(0,30,45,70)
myExpl <- terra::crop(myExpl, myExtent)
})

# ---------------------------------------------------------------#
file.out <- paste0(myRespName, "/", myRespName, ".AllModels.models.out")
if (file.exists(file.out)) {
  myBiomodModelOut <- get(load(file.out))
} else {

  # Format Data with true absences
  myBiomodData <- BIOMOD_FormatingData(resp.name = myRespName,
                                       resp.var = myResp,
                                       resp.xy = myRespXY,
                                       expl.var = myExpl)

  # Model single models
  myBiomodModelOut <- BIOMOD_Modeling(bm.format = myBiomodData,
                                      modeling.id = 'AllModels',
                                      models = c('RF', 'GLM'),
                                      CV.strategy = 'random',
                                      CV.nb.rep = 2,
                                      CV.perc = 0.8,
                                      OPT.strategy = 'bigboss',
                                      metric.eval = c('TSS','AUCroc'),
                                      var.import = 3,
                                      seed.val = 42)
}


# ---------------------------------------------------------------#
# Project single models
file.proj <- paste0(myRespName, "/proj_Current/", myRespName, ".Current.projection.out")
if (file.exists(file.proj)) {
  myBiomodProj <- get(load(file.proj))
} else {
myBiomodProj <- BIOMOD_Projection(bm.mod = myBiomodModelOut,
                                  proj.name = 'Current',
                                  new.env = myExpl,
                                  models.chosen = 'all')
}
myBiomodProj
plot(myBiomodProj)