R/RdistanceControls.R

In Rdistance: Density and Abundance from Distance-Sampling Surveys

#' @title Rdistance optimization control parameters.
#' 
#' @aliases control controls RdistanceControls
#' 
#' @concept control optimization
#' 
#' @description Optimization control parameters 
#' are set by calls to `options()` (see examples). 
#' Optimization parameters used in 
#' `Rdistance` are the following:  
#' 
#' \itemize{
#'   \item `Rdistance_maxIters`: The maximum number of optimization 
#' iterations allowed.
#' 
#'   \item `Rdistance_evalMax`: The maximum number of objective function
#' evaluations allowed.
#' 
#'   \item `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.
#' 
#'   \item `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. 
#'
#'   \item `Rdistance_optimizer`: Normally, this option is not set and 
#'   the default optimizer routines are used. The default optimization 
#'   routine for smooth likelihoods (i.e., listed by 
#'   [differentiableLikelihoods()]) is the gradient-based 
#'   method in [stats::nlminb()]. The default routine for
#'   non-smooth likelihoods is the Nelder-Mead method 
#'   in [stats::optim()]. 
#'   
#'   Not often, but occasionally optimizers fail on problem. Switching 
#'   algorithms can make a poorly behaved distance function converge, 
#'   particularly when parameters are near their boundaries.  
#'   If users wish to override the default optimization routine, 
#'   set this option to one of the following: 
#'   \itemize{
#'    \item "optim_\<method\>": Use the "\<method\>" method in stats::optim. 
#'    For example, "optim_Nelder-Mead" uses 
#'    the Nelder-Mead. See [stats::optim()] for 
#'    documentation of the six available methods. 
#'    \item "nlminb": Uses [stats::nlminb()], a finite-difference
#'    gradient based approach. 
#'    \item "hookeJeeves": Uses [dfoptim::hjkb()], a 
#'    derivative-free approach for continuous and discontinuous 
#'    likelihoods.
#'   }
#'
#'   \item `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. 
#' 
#'   \item `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. 
#'  
#'   \item `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::`[units::valid_udunits()]. 
#' 
#'   \item `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)
#' @name RdistanceControls
NULL