trainMaxEnt: Calibrate a MaxEnt (ver 3.3.3+ or "maxent") model using AICc

In adamlilith/enmSdm: Tools for Modeling Niches and Distributions of Species

Calibrate a MaxEnt (ver 3.3.3+ or "maxent") model using AICc

Description

This function calculates the "best" Maxent model using AICc across all possible combinations of a set of master regularization parameters and feature classes. The best model has the lowest AICc, with ties broken by number of features (fewer is better), regularization multiplier (higher better), then finally the number of coefficients (fewer better). The function can return the best model (default), a list of models created using all possible combinations of feature classes and regularization multipliers, and/or a data frame with tuning statistics for each model. Models in the list and in the data frame are sorted from best to worst. The function requires the maxent jar file (see Details).

Usage

trainMaxEnt(
  data,
  resp = names(data)[1],
  preds = names(data)[2:ncol(data)],
  regMult = c(seq(0.5, 5, by = 0.5), 7.5, 10),
  classes = "default",
  testClasses = TRUE,
  dropOverparam = TRUE,
  anyway = TRUE,
  out = "model",
  forceLinear = TRUE,
  jackknife = FALSE,
  arguments = NULL,
  scratchDir = NULL,
  cores = 1,
  verbose = FALSE,
  ...
)

Arguments

data	Data frame or matrix. Contains a column indicating whether each row is a presence (1) or background (0) site, plus column(s) for environmental predictor(s).
resp	Character or integer. Name or column index of response variable. Default is to use the first column in data.
preds	Character list or integer list. Names of columns or column indices of predictors. Default is to use the second and subsequent columns in data.
regMult	Numeric vector. Values of the master regularization parameters (called beta in some publications) to test.
classes	Character list. Names of feature classes to use (either default to use lpqh) or any combination of lpqht, where l ==> linear features, p ==> product features, q ==> quadratic features, h ==> hinge features, and t ==> threshold features.
testClasses	Logical. If TRUE (default) then test all possible combinations of classes (note that all tested models will at least have linear features). If FALSE then use the classes provided (these will not vary between models).
dropOverparam	Logical, if TRUE (default), drop models if they have more coefficients than training occurrences. It is possible for no models to fulfill this criterion, in which case no models will be returned.
anyway	Logical. Same as dropOverparam (included for backwards compatibility. If NULL (default), then the value of dropOverparam will take precedence. If TRUE or FALSE then anyway will override the value of dropOverparam.
out	Character or character vector. Indicates type of value returned. Values can be 'model' (default; return model with lowest AICc), 'models' (return a list of all models), and/or 'tuning' (return a data frame with AICc for each model). If more than one value is specified, then the output will be a list with elements named "model", "models", and/or "tuning". If 'models' is specified, they will only be produced if select = TRUE. The models will appear in the list in same order as they appear in the tuning table (i.e., model with the lowest AICc first, second-lowest next, etc.). If just one value is specified, the output will be either an object of class MaxEnt, a list with objects of class MaxEnt, or a data frame.
forceLinear	Logical. If TRUE (default) then require any tested models to include at least linear features.
jackknife	Logical. If TRUE (default) the the returned model will be also include jackknife testing of variable importance.
arguments	NULL (default) or a character list. Options to pass to maxent()'s args argument. (Do not include l, p, q, h, t, betamultiplier, or jackknife!)
scratchDir	Character. Directory to which to write temporary files. Leave as NULL to create a temporary folder in the current working directory.
cores	Integer >= 1. Number of cores to use. Default is 1.
verbose	Logical. If TRUE report progress and AICc table.
...	Extra arguments. Not used.

Details

This function is a wrapper for maxent(). That function relies on a maxent jar file being placed into the folder ./library/dismo/java. See maxent for more details. The maxent() function creates a series of files on disc for each model. This function assumes you do not want those files, so deletes most of them. However, there is one that cannot be deleted and the normal ways of changing its permissions in R do not work. So the function simply writes over that file (which is allowed) to make it smaller. Regardless, if you run many models your temporary directory (argument scratchDir) can fill up and require manual deletion.

Value

If out = 'model' this function returns an object of class MaxEnt. If out = 'tuning' this function returns a data frame with tuning parameters, log likelihood, and AICc for each model tried. If out = c('model', 'tuning' then it returns a list object with the MaxEnt object and the data frame.

References

Warren, D.L. and S.N. Siefert. 2011. Ecological niche modeling in Maxent: The importance of model complexity and the performance of model selection criteria. Ecological Applications 21:335-342.

See Also

maxnet, maxent, trainMaxNet

Examples

### model red-bellied lemurs
data(mad0)
data(lemurs)

# climate data
bios <- c(1, 5, 12, 15)
clim <- raster::getData('worldclim', var='bio', res=10)
clim <- raster::subset(clim, bios)
clim <- raster::crop(clim, mad0)

# occurrence data
occs <- lemurs[lemurs$species == 'Eulemur rubriventer', ]
occsEnv <- raster::extract(clim, occs[ , c('longitude', 'latitude')])
occsEnv <- as.data.frame(occsEnv) # need to do this for prediction later

# background sites
bg <- 2000 # too few cells to locate 10000 background points
bgSites <- dismo::randomPoints(clim, 2000)
bgEnv <- raster::extract(clim, bgSites)

# collate
presBg <- rep(c(1, 0), c(nrow(occs), nrow(bgSites)))
env <- rbind(occsEnv, bgEnv)
env <- cbind(presBg, env)
env <- as.data.frame(env)

preds <- paste0('bio', bios)

regMult <- 1:3 # default values are probably better, but these will be faster

# calibrate MaxEnt model
ent <- trainMaxEnt(
	data=env,
	resp='presBg',
	preds=preds,
	regMult=regMult,
	classes='lpq',
	verbose=TRUE
)

# calibrate MaxNet model
net <- trainMaxNet(
	data=env,
	resp='presBg',
	preds=preds,
	regMult=regMult,
	classes='lpq',
	verbose=TRUE
)

# prediction rasters
mapEnt <- predict(ent, clim, type='logistic')
mapNet <- predict(clim, net, type='logistic')

par(mfrow=c(1, 2))
plot(mapEnt, main='MaxEnt')
points(occs[ , c('longitude', 'latitude')])
plot(mapNet, main='MaxNet')
points(occs[ , c('longitude', 'latitude')])

# predictions to occurrences
(dismo::predict(ent, occsEnv, args=c('outputformat=logistic')))
(enmSdm::predictMaxEnt(ent, occsEnv, type='logistic'))
(c(predict(net, occsEnv, type='logistic')))

# note the differences between the tuning of the two models...
# this is because maxnet() (used by trainMaxNet())
# uses an approximation:
# (note maxnet() calculates hinges and thresholds differently
# so we will turn them off)

data(bradypus, package='maxnet')
p <- bradypus$presence
data <- bradypus[ , 2:3] # easier to inspect betas
mn <- maxnet::maxnet(p, data,
maxnet::maxnet.formula(p, data, classes='lpq'))
mx <- dismo::maxent(data, p,
args=c('linear=true', 'product=true', 'quadratic=true', 'hinge=false',
'threshold=false'))

predMx <- dismo::predict(mx, data)
predMn <- predict(mn, data, type='logistic')

par(mfrow=c(1, 1))
plot(predMx, predMn)
abline(0, 1)

adamlilith/enmSdm documentation built on Jan. 6, 2023, 11 a.m.