BIOMOD_Modeling {biomod2} | R Documentation |
Run a range of species distribution models
Description
This function allows to calibrate and evaluate a range of modeling techniques for a given species distribution. The dataset can be split up in calibration/validation parts, and the predictive power of the different models can be estimated using a range of evaluation metrics (see Details).
Usage
BIOMOD_Modeling(
bm.format,
modeling.id = as.character(format(Sys.time(), "%s")),
models = c("ANN", "CTA", "FDA", "GAM", "GBM", "GLM", "MARS", "MAXENT", "MAXNET", "RF",
"SRE", "XGBOOST"),
models.pa = NULL,
CV.strategy = "random",
CV.nb.rep = 1,
CV.perc = NULL,
CV.k = NULL,
CV.balance = NULL,
CV.env.var = NULL,
CV.strat = NULL,
CV.user.table = NULL,
CV.do.full.models = TRUE,
OPT.data.type = "binary",
OPT.strategy = "default",
OPT.user.val = NULL,
OPT.user.base = "bigboss",
OPT.user = NULL,
bm.options,
nb.rep,
data.split.perc,
data.split.table,
do.full.models,
weights = NULL,
prevalence = NULL,
metric.eval = c("KAPPA", "TSS", "ROC"),
var.import = 0,
scale.models = FALSE,
nb.cpu = 1,
seed.val = NULL,
do.progress = TRUE
)
Arguments
bm.format |
a |
modeling.id |
a |
models |
a |
models.pa |
(optional, default |
CV.strategy |
a |
CV.nb.rep |
(optional, default |
CV.perc |
(optional, default |
CV.k |
(optional, default |
CV.balance |
(optional, default |
CV.env.var |
(optional) |
CV.strat |
(optional, default |
CV.user.table |
(optional, default |
CV.do.full.models |
(optional, default |
OPT.data.type |
a |
OPT.strategy |
a |
OPT.user.val |
(optional, default |
OPT.user.base |
(optional, default |
OPT.user |
(optional, default |
bm.options |
a |
nb.rep |
deprecated, now called |
data.split.perc |
deprecated, now called |
data.split.table |
deprecated, now called |
do.full.models |
deprecated, now called |
weights |
(optional, default |
prevalence |
(optional, default |
metric.eval |
a |
var.import |
(optional, default |
scale.models |
(optional, default |
nb.cpu |
(optional, default |
seed.val |
(optional, default |
do.progress |
(optional, default |
Details
- bm.format
If pseudo absences have been added to the original dataset (see
BIOMOD_FormatingData
),
PA.nb.rep *(nb.rep + 1)
models will be created.- models
The set of models to be calibrated on the data. 12 modeling techniques are currently available :
-
ANN
: Artificial Neural Network (nnet
) -
CTA
: Classification Tree Analysis (rpart
) -
FDA
: Flexible Discriminant Analysis (fda
) -
GAM
: Generalized Additive Model (gam
,gam
orbam
)
(seebm_ModelingOptions for details on algorithm selection
) -
GBM
: Generalized Boosting Model, or usually called Boosted Regression Trees (gbm
) -
GLM
: Generalized Linear Model (glm
) -
MARS
: Multiple Adaptive Regression Splines (earth
) -
MAXENT
: Maximum Entropy (https://biodiversityinformatics.amnh.org/open_source/maxent/) -
MAXNET
: Maximum Entropy (maxnet
) -
RF
: Random Forest (randomForest
) -
SRE
: Surface Range Envelop or usually called BIOCLIM (bm_SRE
) -
XGBOOST
: eXtreme Gradient Boosting Training (xgboost
)
-
- models.pa
Different models might respond differently to different numbers of pseudo-absences. It is possible to create sets of pseudo-absences with different numbers of points (see
BIOMOD_FormatingData
) and to assign only some of these datasets to each single model.- CV.[...] parameters
Different methods are available to calibrate/validate the single models (see
bm_CrossValidation
).- OPT.[...] parameters
Different methods are available to parameterize the single models (see
bm_ModelingOptions
andBIOMOD.options.dataset
). Note that onlybinary
data type is allowed currently.-
default
: only default parameter values of default parameters of the single models functions are retrieved. Nothing is changed so it might not give good results. -
bigboss
: uses parameters pre-defined by biomod2 team and that are available in the datasetOptionsBigboss
.
to be optimized in near future -
user.defined
: updates default or bigboss parameters with some parameters values defined by the user (but matching the format of aBIOMOD.models.options
object) -
tuned
: calling thebm_Tuning
function to try and optimize some default values
-
- weights & prevalence
More or less weight can be given to some specific observations.
If
weights = prevalence = NULL
, each observation (presence or absence) will have the same weight, no matter the total number of presences and absences.If
prevalence = 0.5
, presences and absences will be weighted equally (i.e. the weighted sum of presences equals the weighted sum of absences).If
prevalence
is set below (above)0.5
, more weight will be given to absences (presences).If
weights
is defined,prevalence
argument will be ignored, and each observation will have its own weight.If pseudo-absences have been generated (
PA.nb.rep > 0
inBIOMOD_FormatingData
), weights are by default calculated such thatprevalence = 0.5
. Automatically createdweights
will beinteger
values to prevent some modeling issues.
- metric.eval
-
- simple
-
-
POD
: Probability of detection (hit rate) -
FAR
: False alarm ratio -
POFD
: Probability of false detection (fall-out) -
SR
: Success ratio -
ACCURACY
: Accuracy (fraction correct) -
BIAS
: Bias score (frequency bias)
-
- complex
-
-
ROC
: Relative operating characteristic -
TSS
: True skill statistic (Hanssen and Kuipers discriminant, Peirce's skill score) -
KAPPA
: Cohen's Kappa (Heidke skill score) -
OR
: Odds Ratio -
ORSS
: Odds ratio skill score (Yule's Q) -
CSI
: Critical success index (threat score) -
ETS
: Equitable threat score (Gilbert skill score)
-
- presence-only
-
-
BOYCE
: Boyce index -
MPA
: Minimal predicted area (cutoff optimising MPA to predict 90% of presences)
-
Optimal value of each method can be obtained with the
get_optim_value
function. Several evaluation metrics can be selected. Please refer to the CAWRC website (section "Methods for dichotomous forecasts") to get detailed description of each metric. Results after modeling can be obtained through theget_evaluations
function.
Evaluation metric are calculated on the calibrating data (columncalibration
), on the cross-validation data (columnvalidation
) or on the evaluation data (columnevaluation
).
For cross-validation data, seeCV.[...]
parameters inBIOMOD_Modeling
function ; for evaluation data, seeeval.[...]
parameters inBIOMOD_FormatingData
. - var.import
A value caracterizing how much each variable has an impact on each model predictions can be calculated by randomizing the variable of interest and computing the correlation between original and shuffled variables (see
bm_VariablesImportance
).- scale.models
This parameter is quite experimental and it is recommended not to use it. It may lead to reduction in projection scale amplitude. Some categorical models always have to be scaled (
FDA
,ANN
), but it may be interesting to scale all computed models to ensure comparable predictions (0-1000
range). It might be particularly useful when doing ensemble forecasting to remove the scale prediction effect (the more extended projections are, the more they influence ensemble forecasting results).
Value
A BIOMOD.models.out
object containing models outputs, or links to saved outputs.
Models outputs are stored out of R (for memory storage reasons) in 2 different folders
created in the current working directory :
a models folder, named after the
resp.name
argument ofBIOMOD_FormatingData
, and containing all calibrated models for each repetition and pseudo-absence runa hidden folder, named
.BIOMOD_DATA
, and containing outputs related files (original dataset, calibration lines, pseudo-absences selected, predictions, variables importance, evaluation values...), that can be retrieved withget_[...]
orload
functions, and used by other biomod2 functions, likeBIOMOD_Projection
orBIOMOD_EnsembleModeling
Author(s)
Wilfried Thuiller, Damien Georges, Robin Engler
See Also
glm
, gam
,
gam
, bam
, gbm
,
rpart
, nnet
,
fda
, earth
,
randomForest
, maxnet
,
xgboost
, BIOMOD_FormatingData
,
bm_ModelingOptions
, bm_Tuning
,
bm_CrossValidation
,
bm_VariablesImportance
, BIOMOD_Projection
,
BIOMOD_EnsembleModeling
, bm_PlotEvalMean
,
bm_PlotEvalBoxplot
, bm_PlotVarImpBoxplot
,
bm_PlotResponseCurves
Other Main functions:
BIOMOD_EnsembleForecasting()
,
BIOMOD_EnsembleModeling()
,
BIOMOD_FormatingData()
,
BIOMOD_LoadModels()
,
BIOMOD_Projection()
,
BIOMOD_RangeSize()
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)
# ---------------------------------------------------------------------------- #
# 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 = 2,
seed.val = 42)
myBiomodModelOut
# Get evaluation scores & variables importance
get_evaluations(myBiomodModelOut)
get_variables_importance(myBiomodModelOut)
# Represent evaluation scores
bm_PlotEvalMean(bm.out = myBiomodModelOut, dataset = 'calibration')
bm_PlotEvalMean(bm.out = myBiomodModelOut, dataset = 'validation')
bm_PlotEvalBoxplot(bm.out = myBiomodModelOut, group.by = c('algo', 'run'))
# # Represent variables importance
# bm_PlotVarImpBoxplot(bm.out = myBiomodModelOut, group.by = c('expl.var', 'algo', 'algo'))
# bm_PlotVarImpBoxplot(bm.out = myBiomodModelOut, group.by = c('expl.var', 'algo', 'run'))
# bm_PlotVarImpBoxplot(bm.out = myBiomodModelOut, group.by = c('algo', 'expl.var', 'run'))
# # Represent response curves
# mods <- get_built_models(myBiomodModelOut, run = 'RUN1')
# bm_PlotResponseCurves(bm.out = myBiomodModelOut,
# models.chosen = mods,
# fixed.var = 'median')
# bm_PlotResponseCurves(bm.out = myBiomodModelOut,
# models.chosen = mods,
# fixed.var = 'min')
# mods <- get_built_models(myBiomodModelOut, full.name = 'GuloGulo_allData_RUN2_RF')
# bm_PlotResponseCurves(bm.out = myBiomodModelOut,
# models.chosen = mods,
# fixed.var = 'median',
# do.bivariate = TRUE)