Internal functions to tune and summarize results for ecological niche models (ENMs) iteratively across a range of user-specified tuning settings.
See ENMevaluate for descriptions of shared arguments.
Function tune.parallel()
tunes ENMs with parallelization. Function cv.enm()
calculates training and validation evaluation statistics for one set of specified tuning parameters.
Validation CBI is calculated here with background values, not raster data, in order
to standardize the methodology for both training and validation data for spatial partitions, as ENMeval
does not mask rasters to partition areas and hence does not have partitioned raster data. Further,
predictions for occurrence and background localities are combined as input for the parameter "fit" in
ecospat::ecospat_boyce()
because the interval is determined from "fit" only, and if test occurrences
all have higher predictions than the background, the interval will be cut short.
tune.train(
enm,
occs.z,
bg.z,
mod.full,
envs,
tune.tbl.i,
other.settings,
partitions,
quiet
)tune.validate(
enm,
occs.train.z,
occs.val.z,
bg.train.z,
bg.val.z,
mod.k,
nk,
tune.tbl.i,
other.settings,
partitions,
user.eval,
quiet
)
tune.parallel(
d,
envs,
enm,
partitions,
tune.tbl,
doClamp,
other.settings,
partition.settings,
user.val.grps,
occs.testing.z,
numCores,
parallelType,
user.eval,
algorithm,
quiet
)
tune.regular(
d,
envs,
enm,
partitions,
tune.tbl,
doClamp,
other.settings,
partition.settings,
user.val.grps,
occs.testing.z,
updateProgress,
user.eval,
algorithm,
quiet
)
cv.enm(
d,
envs,
enm,
partitions,
tune.tbl.i,
doClamp,
other.settings,
partition.settings,
user.val.grps,
occs.testing.z,
user.eval,
algorithm,
quiet
)
ENMdetails object
data.frame: the envs values for the coordinates at the full dataset occurrence records
data.frame: the envs values for the coordinates at the full dataset background records
model object: the model trained on the full dataset
RasterStack: environmental predictor variables. These should be in same geographic projection as occurrence data.
vector: single set of tuning parameters
named list: used to specify extra settings for the analysis. All of these settings have internal defaults, so if they are not specified the analysis will be run with default settings. See Details for descriptions of these settings, including how to specify arguments for maxent.jar.
character: name of partitioning technique (see ?partitions
)
boolean: if TRUE, silence all function messages (but not errors).
data.frame: the envs values for the coordinates at the training occurrence records
data.frame: the envs values for the coordinates at the validation occurrence records
data.frame: the envs values for the coordinates at the training background records
data.frame: the envs values for the coordinates at the validation background records
model object: the model trained on the training dataset that becomes evaluated on the validation data
numeric: the number of folds (i.e., partitions) -- will be equal to kfolds
for random partitions
function: custom function for specifying performance metrics not included in ENMeval.
The function must first be defined and then input as the argument user.eval
.
This function should have a single argument called vars
, which is a list that includes different data
that can be used to calculate the metric. See Details below and the vignette for a worked example.
data frame: data frame from ENMevaluate()
with occurrence and background coordinates (or coordinates plus predictor variable values) and partition group values
data frame: all combinations of tuning parameters
boolean: if TRUE (default), model prediction extrapolations will be restricted to the upper and lower bounds of the predictor variables. Clamping avoids extreme predictions for environment values outside the range of the training data. If free extrapolation is a study aim, this should be set to FALSE, but for most applications leaving this at the default of TRUE is advisable to avoid unrealistic predictions. When predictor variables are input, they are clamped internally before making model predictions when clamping is on. When no predictor variables are input and data frames of variable values are used instead (SWD format), validation data is clamped before making model predictions when clamping is on.
named list: used to specify certain settings for partitioning schema. See Details and ?partitions for descriptions of these settings.
matrix / data frame: user-defined validation record coordinates and predictor variable values.
This is used internally by ENMnulls()
to force each null model to evaluate with empirical validation data,
and does not have any current use when running ENMevaluate()
independently.
data.frame: when fully withheld testing data is provided, the envs values for the coordinates at the testing occurrence records
numeric: number of cores to use for parallel processing. If NULL, all available cores will be used.
character: either "doParallel" or "doSNOW" (default: "doSNOW") .
character: name of the algorithm used to build models. Currently one of "maxnet", "maxent.jar", or "bioclim", else the name from a custom ENMdetails implementation.
boolean: if TRUE, use shiny progress bar. This is only for use in shiny apps.