RdistanceControls: Control parameters for 'Rdistance' optimization.

View source: R/RdistanceControls.R

RdistanceControlsR Documentation

Control parameters for Rdistance optimization.

Description

Returns a list of optimization controls used in Rdistance and provides a way to change them if needed.

Usage

RdistanceControls(
  optimizer = "nlminb",
  evalMax = 2000,
  maxIters = 1000,
  likeTol = 1e-08,
  coefTol = 1.5e-08,
  hessEps = 1e-08,
  requireUnits = TRUE,
  maxBSFailPropForWarning = 0.2,
  contrasts = NULL
)

Arguments

optimizer

A string specifying the optimizer to use. Results vary between optimizers, so switching algorithms sometimes makes a poorly behaved distance function converge. The valid values are "optim" which uses optim::optim, and "nlminb" which uses stats:nlminb. The authors have had better luck with "nlminb" than "optim" and "nlminb" runs noticeably faster. Problems with solutions near parameter boundaries may require use of "optim".

evalMax

The maximum number of objective function evaluations allowed.

maxIters

The maximum number of optimization iterations allowed.

likeTol

The maximum change in the likelihood (the objective) between iterations that is tolerated during optimization. If the likelihood changes by less than this amount, optimization stops and a solution is declared.

coefTol

The maximum change in the model coefficients between iterations that is tolerated during optimization. If the sum of squared coefficient differences changes by less than this amount between iterations, optimization stops and a solution is declared.

hessEps

A vector of parameter distances used during computation of numeric second derivatives. Should have length 1 or the number of parameters in the model. See function secondDeriv.

requireUnits

A logical specifying whether measurement units are required on distances and areas. If TRUE, measurement units are required on off-transect and radial distances in the input data frame. Likewise, measurement units are required on transect length and study area size. Assign units with statement like units(detectionDf$dist) <- "m" or units(df$transectDf) <- "km". Measurement units do not need to be the same. All units are converted appropriately during internal computations. Rdistance recognizes units listed in units::valid_udunits().

maxBSFailPropForWarning

The proportion of bootstrap iterations that can fail without a warning. If the proportion of bootstrap iterations that did not converge exceeds this parameter, a warning about the validity of CI's is issued in the print method for abundance objects.

contrasts

A list, whose entries are values (numeric matrices, functions or character strings naming functions) to be used as replacement values for the default contrasts function and whose names are the names of columns of data containing factors.

There are several ways to change the contrasts used for factors in Rdistance because all methods used in linear models (lm) work. To summarize contrast methods in R, if this parameter is NULL, Rdistance uses the global contrasts specified in options(). To change the global contrasts, use a statement like options(contrasts = c(unordered = "contr.SAS", ordered = "contr.poly")). One can also set contrasts for a factor using contrasts(a) (e.g., contrasts(a) <- "contr.sum") Lastly, one can set this parameter to a list that explicitely states the non-global contrasts to use for which factors in the Rdistance model. For example, list(a = "contr.helmert") will use Helmert contrasts for a and the global contrast option for all other factors. The built-in R contrast functions are "contr.treatment", "contr.helmert", "contr.SAS", "contr.sum", and "contr.poly".

Value

A list containing named components for each of the controls. This list has the same components as this function has input parameters.

Examples

# increase number of iterations
RdistanceControls(maxIters=2000)

# change optimizer and decrease tolerance
RdistanceControls(optimizer="optim", likeTol=1e-6) 


Rdistance documentation built on July 9, 2023, 6:46 p.m.