R/BIOMOD_EnsembleForecasting.R
BIOMOD_EnsembleForecasting.RdThis function allows to project ensemble models built with the
BIOMOD_EnsembleModeling function onto new environmental data
(which can represent new areas, resolution or time scales for example).
BIOMOD_EnsembleForecasting(
bm.em,
bm.proj = NULL,
proj.name = NULL,
new.env = NULL,
new.env.xy = NULL,
models.chosen = "all",
metric.binary = NULL,
metric.filter = NULL,
compress = TRUE,
nb.cpu = 1,
na.rm = TRUE,
...
)a BIOMOD.ensemble.models.out object returned by the
BIOMOD_EnsembleModeling function
a BIOMOD.projection.out object returned by the
BIOMOD_Projection function
(optional, default NULL)
If bm.proj = NULL, a character corresponding to the name (ID) of the
projection set (a new folder will be created within the simulation folder with this
name)
(optional, default NULL)
If bm.proj = NULL, 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.
(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 ensemble species distribution model(s)
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
(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 modeling.output) or POD, FAR, POFD, SR,
ACCURACY, BIAS, ROC, TSS, KAPPA, OR, ORSS,
CSI, ETS, BOYCE, MPA
(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 modeling.output) or POD, FAR, POFD, SR,
ACCURACY, BIAS, ROC, TSS, KAPPA, OR, ORSS,
CSI, ETS, BOYCE, MPA
(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, xz or
gzip (see Details)
(optional, default 1)
An integer value corresponding to the number of computing resources to be used to
parallelize the single models computation
(optional, default TRUE)
A boolean defining whether Ensemble Model projection should ignore NA
in Individual Model projection. Argument ignored by EWmean ensemble algorithm.
(optional, see Details)
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
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 :
on_0_1000 : a logical value defining whether 0 - 1
probabilities are to be converted to 0 - 1000 scale to save memory on backup
do.stack : 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)
keep.in.memory : 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
output.format : 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)
BIOMOD_FormatingData, bm_ModelingOptions,
BIOMOD_Modeling, BIOMOD_EnsembleModeling,
BIOMOD_RangeSize
Other Main functions:
BIOMOD_EnsembleModeling(),
BIOMOD_FormatingData(),
BIOMOD_LoadModels(),
BIOMOD_Modeling(),
BIOMOD_Projection(),
BIOMOD_RangeSize()
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.var = myResp,
expl.var = myExpl,
resp.xy = myRespXY,
resp.name = myRespName)
# 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','ROC'),
var.import = 3,
seed.val = 42)
}
file.proj <- paste0(myRespName, "/proj_Current/", myRespName, ".Current.projection.out")
if (file.exists(file.proj)) {
myBiomodProj <- get(load(file.proj))
} else {
# Project single models
myBiomodProj <- BIOMOD_Projection(bm.mod = myBiomodModelOut,
proj.name = 'Current',
new.env = myExpl,
models.chosen = 'all',
build.clamping.mask = TRUE)
}
file.EM <- paste0(myRespName, "/", myRespName, ".AllModels.ensemble.models.out")
if (file.exists(file.EM)) {
myBiomodEM <- get(load(file.EM))
} else {
# Model ensemble models
myBiomodEM <- BIOMOD_EnsembleModeling(bm.mod = myBiomodModelOut,
models.chosen = 'all',
em.by = 'all',
em.algo = c('EMmean', 'EMca'),
metric.select = c('TSS'),
metric.select.thresh = c(0.7),
metric.eval = c('TSS', 'ROC'),
var.import = 3,
seed.val = 42)
}
# --------------------------------------------------------------- #
# Project ensemble models (from single projections)
myBiomodEMProj <- BIOMOD_EnsembleForecasting(bm.em = myBiomodEM,
bm.proj = myBiomodProj,
models.chosen = 'all',
metric.binary = 'all',
metric.filter = 'all')
# Project ensemble models (building single projections)
myBiomodEMProj <- BIOMOD_EnsembleForecasting(bm.em = myBiomodEM,
proj.name = 'CurrentEM',
new.env = myExpl,
models.chosen = 'all',
metric.binary = 'all',
metric.filter = 'all')
myBiomodEMProj
plot(myBiomodEMProj)