RdistanceControls: Rdistance optimization control parameters.

In Rdistance: Density and Abundance from Distance-Sampling Surveys

Rdistance optimization control parameters.

Description

Optimization control parameters are set by calls to options() (see examples). Optimization parameters used in Rdistance are the following:

• Rdistance_maxIters: The maximum number of optimization iterations allowed.

• Rdistance_evalMax: The maximum number of objective function evaluations allowed.

• Rdistance_likeTol: Minimum change in the likelihood between iterations required optimization to continue. If the likelihood changes by less than this amount, optimization stops and a solution is declared. Iteration continues when likelihood changes exceed this value.

• Rdistance_coefTol: Minimum change in model coefficients between iterations for optimization to continue. If the sum of squared coefficient differences changes by less than this amount between iterations, optimization stops and a solution is declared.

• Rdistance_optimizer: A string specifying the optimizer to use. Results do not often, but can vary among optimizers, so switching algorithms sometimes makes a poorly behaved distance function converge, particularly when parameters are near their boundaries. Gradient based methods are only appropriate for smooth likelihoods. Valid values are:

  • "default": If the likelihood is smooth, i.e., listed in the output of differentiableLikelihoods(), optimization defaults to the gradient-based method in nlminb. If the likelihood is not smooth, optimization defaults to the Nelder-Mead method in optim.

  • "optim_<method>": Uses the "<method>" method in stats::optim. For example, "optim_Nelder-Mead" uses the Nelder-Mead method in optim. See optim for documentation of the six available methods.

  • "nlminb": Uses nlminb, a finite-difference gradient based approach.

  • "hookeJeeves": Uses hjkb, a derivative-free approach for continuous and discontinuous likelihoods.

  The authors recommend "nlminb" when likelihoods are differentiable (i.e. smooth). "optim_Nelder-Mead" is recommended for non-smooth likelihoods. "optim_Nelder-Mead" also performs better when solutions are near, but not on, parameter boundaries. "hookeJeeves" works well in all cases but can be slower than the others. All methods can be applied to smooth likelihoods, but only gradient-free methods can be applied to discontinuous likelihoods (such as oneStep and triangle).

• Rdistance_hessEps: A vector of parameter distances used during computation of numeric second derivatives. These distances control and determine variance estimates, and they may need revision when the maximum likelihood solution is near a parameter boundary. Should have length 1 or the number of parameters in the model. See function secondDeriv for further details.

• Rdistance_trace: Integer scalar for the level of information printed to the console by the optimization routine during maximization of the likelihood. All optimizer routines interpret a value of 0 as 'do not print any information' or silent. Higher values produce more information. The information produced varies among optimization routines.

• Rdistance_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 truncation distances, scale location, transect lengths, and study area size. If FALSE, no units are required and input values are used as is. The FALSE options is provided for rare cases when Rdistance functions are called from other functions and the calling functions do not accommodate units.

  Assign units with statement like units(detectionDf$dist) <- "m" or setUnits(w.hi, "km") or w.hi <- 150 %#% "m" or w.hi <- 150 %m%.. Measurement units of the various physical quantities need not be equal because appropriate conversions occur internally. An error is thrown if differing units are not compatible. For example, "m" (meters) cannot be converted into "ha" (hectares), but "acres" can be converted into "ha". Rdistance recognizes units listed in units::valid_udunits.

• Rdistance_maxBSFailPropForWarning: The proportion of bootstrap iterations that can fail without a warning. If the proportion of non-convergent bootstrap iterations exceeds this parameter, a warning about the validity of CI's is issued in the abundance print method.

Examples

# increase number of iterations
options(Rdistance_maxIters=2000)

# change optimizer and decrease tolerance
op <- options(list(Rdistance_optimizer="optim_Nelder-Mead"
                 , Rdistance_likeTol=1e-6)) 

# change back
options(op)

Rdistance documentation built on April 23, 2026, 1:06 a.m.