Configure the modeling options for each selected model

Source: R/bm_ModelingOptions.R

Parameterize and/or tune biomod2's single models options.

bm_ModelingOptions(
  data.type,
  models = c("ANN", "CTA", "FDA", "GAM", "GBM", "GLM", "MARS", "MAXENT", "MAXNET", "RF",
    "RFd", "SRE", "XGBOOST"),
  strategy,
  user.val = NULL,
  user.base = "bigboss",
  bm.format = NULL,
  calib.lines = NULL
)

Arguments

data.type

a character corresponding to the data type to be used, must be either binary, binary.PA, abundance, compositional. For the moment, only binary is accept.

models

a vector containing model names to be computed, must be among ANN, CTA, FDA, GAM, GBM, GLM, MARS, MAXENT, MAXNET, RF, RFd, SRE, XGBOOST

strategy

a character corresponding to the method to select models' parameters values, must be either default, bigboss, user.defined, tuned

user.val

(optional, default NULL)
A list containing parameters values for some (all) models

user.base

(optional, default bigboss)
A character, default or bigboss used when strategy = 'user.defined'. It sets the bases of parameters to be modified by user defined values.

bm.format

(optional, default NULL)
A BIOMOD.formated.data or BIOMOD.formated.data.PA object returned by the BIOMOD_FormatingData function

calib.lines

(optional, default NULL)
A data.frame object returned by get_calib_lines or bm_CrossValidation functions

Value

A BIOMOD.models.options of object that can be used to build species distribution model(s) with the BIOMOD_Modeling function.

Details

This function creates a BIOMOD.models.options object containing parameter values for each single model that can be run within biomod2 through BIOMOD_Modeling function.

12 models are currently available, and are listed within the ModelsTable dataset.

Different strategies are available to set those parameters, through the strategy argument :

default

all parameters names and values are directly retrieve from functions to be called through formalArgs and formals functions respectively

bigboss

default parameter values are updated with values predefined by biomod2 team

user.defined

default parameter values are updated with values provided by the user

tuned

default parameter values are updated by calling bm_Tuning function

To define the same options for all datasets of a model, you can provide these options as a list in user.val with the names "for_all_datasets".

Note

MAXENT being the only external model (not called through a R package), default parameters, and their values, are the following :

  • path_to_maxent.jar = getwd() : a character corresponding to path to maxent.jar file

  • memory_allocated = 512 : an integer corresponding to the amount of memory (in Mo) reserved for java to run MAXENT, must be either 64, 128, 256, 512, 1024... or NULL to use default java memory limitation parameter

  • initial_heap_size = NULL : a character corresponding to initial heap space (shared memory space) allocated to java (argument -Xms when calling java), must be either 1024K, 4096M, 10G ... or NULL to use default java parameter. Used in BIOMOD_Projection but not in BIOMOD_Modeling.

  • max_heap_size = NULL : a character corresponding to maximum heap space (shared memory space) allocated to java (argument -Xmx when calling java), must be either 1024K, 4096M, 10G ... or NULL to use default java parameter, and must be larger than initial_heap_size. Used in BIOMOD_Projection but not in BIOMOD_Modeling.

  • background_data_dir = 'default' : a character corresponding to path to folder where explanatory variables are stored as ASCII files (raster format). If specified, MAXENT will generate its own background data from rasters of explanatory variables ('default' value). Otherwise biomod2 pseudo-absences will be used (see BIOMOD_FormatingData).

  • visible = FALSE : a logical value defining whether MAXENT user interface is to be used or not

  • linear = TRUE : a logical value defining whether linear features are to be used or not

  • quadratic = TRUE : a logical value defining whether quadratic features are to be used or not

  • product = TRUE : a logical value defining whether product features are to be used or not

  • threshold = TRUE : a logical value defining whether threshold features are to be used or not

  • hinge = TRUE : a logical value defining whether hinge features are to be used or not

  • l2lqthreshold = 10 : an integer corresponding to the number of samples at which quadratic features start being used

  • lq2lqptthreshold = 80 : an integer corresponding to the number of samples at which product and threshold features start being used

  • hingethreshold = 15 : an integer corresponding to the number of samples at which hinge features start being used

  • beta_lqp = -1.0 : a numeric corresponding to the regularization parameter to be applied to all linear, quadratic and product features (negative value enables automatic setting)

  • beta_threshold = -1.0 : a numeric corresponding to the regularization parameter to be applied to all threshold features (negative value enables automatic setting)

  • beta_hinge = -1.0 : a numeric corresponding to the regularization parameter to be applied to all hinge features (negative value enables automatic setting)

  • beta_categorical = -1.0 : a numeric corresponding to the regularization parameter to be applied to all categorical features (negative value enables automatic setting)

  • betamultiplier = 1 : a numeric corresponding to the number by which multiply all automatic regularization parameters (higher number gives a more spread-out distribution)

  • defaultprevalence = 0.5 : a numeric corresponding to the default prevalence of the modelled species (probability of presence at ordinary occurrence points)

Author

Damien Georges, Wilfried Thuiller, Maya Gueguen

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)
})

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

# k-fold selection
cv.k <- bm_CrossValidation(bm.format = myBiomodData,
                           strategy = 'kfold',
                           nb.rep = 2,
                           k = 3)


# ---------------------------------------------------------------#
allModels <- c('ANN', 'CTA', 'FDA', 'GAM', 'GBM', 'GLM'
               , 'MARS', 'MAXENT', 'MAXNET', 'RF', 'SRE', 'XGBOOST')

# default parameters
opt.d <- bm_ModelingOptions(data.type = 'binary',
                            models = allModels,
                            strategy = 'default')

# providing formated data
opt.df <- bm_ModelingOptions(data.type = 'binary',
                             models = allModels,
                             strategy = 'default',
                             bm.format = myBiomodData,
                             calib.lines = cv.k)

opt.d
opt.d@models
opt.d@options$ANN.binary.nnet.nnet
names(opt.d@options$ANN.binary.nnet.nnet@args.values)

opt.df@options$ANN.binary.nnet.nnet
names(opt.df@options$ANN.binary.nnet.nnet@args.values)


# ---------------------------------------------------------------#
# bigboss parameters
opt.b <- bm_ModelingOptions(data.type = 'binary',
                            models = allModels,
                            strategy = 'bigboss')

# user defined parameters
user.SRE <- list('_allData_allRun' = list(quant = 0.01))
user.XGBOOST <- list('_allData_allRun' = list(nrounds = 10))
user.val <- list(SRE.binary.biomod2.bm_SRE = user.SRE
                 , XGBOOST.binary.xgboost.xgboost = user.XGBOOST)

opt.u <- bm_ModelingOptions(data.type = 'binary',
                            models = c('SRE', 'XGBOOST'),
                            strategy = 'user.defined',
                            user.val = user.val)

opt.b
opt.u

if (FALSE) { # \dontrun{
# tuned parameters with formated data
opt.t <- bm_ModelingOptions(data.type = 'binary',
                            models = c('SRE', 'XGBOOST'),
                            strategy = 'tuned',
                            bm.format = myBiomodData)
opt.t
} # }