Setting GAM fitting defaults - R Documentation

`gam.control` Setting GAM fitting defaults

Description

This is an internal function of package mgcv which allows control of the numerical options for fitting a GAM. Typically users will want to modify the defaults if model fitting fails to converge, or if the warnings are generated which suggest a loss of numerical stability during fitting. To change the default choise of fitting method, see gam arguments method and optimizer.

Usage

gam.control(nthreads=1,irls.reg=0.0,epsilon = 1e-07, maxit = 200,
            mgcv.tol=1e-7,mgcv.half=15, trace = FALSE,
            rank.tol=.Machine$double.eps^0.5,nlm=list(),
	    optim=list(),newton=list(),outerPIsteps=0,
	    idLinksBases=TRUE,scalePenalty=TRUE,efs.lspmax=15,
	    efs.tol=.1,keepData=FALSE,scale.est="fletcher",
	    edge.correct=FALSE)

Arguments

`nthreads`	Some parts of some smoothing parameter selection methods (e.g. REML) can use some parallelization in the C code if your R installation supports openMP, and `nthreads` is set to more than 1. Note that it is usually better to use the number of physical cores here, rather than the number of hyper-threading cores.
`irls.reg`	For most models this should be 0. The iteratively re-weighted least squares method by which GAMs are fitted can fail to converge in some circumstances. For example, data with many zeroes can cause problems in a model with a log link, because a mean of zero corresponds to an infinite range of linear predictor values. Such convergence problems are caused by a fundamental lack of identifiability, but do not show up as lack of identifiability in the penalized linear model problems that have to be solved at each stage of iteration. In such circumstances it is possible to apply a ridge regression penalty to the model to impose identifiability, and `irls.reg` is the size of the penalty.
`epsilon`	This is used for judging conversion of the GLM IRLS loop in `gam.fit` or `gam.fit3`.
`maxit`	Maximum number of IRLS iterations to perform.
`mgcv.tol`	The convergence tolerance parameter to use in GCV/UBRE optimization.
`mgcv.half`	If a step of the GCV/UBRE optimization method leads to a worse GCV/UBRE score, then the step length is halved. This is the number of halvings to try before giving up.
`trace`	Set this to `TRUE` to turn on diagnostic output.
`rank.tol`	The tolerance used to estimate the rank of the fitting problem.
`nlm`	list of control parameters to pass to `nlm` if this is used for outer estimation of smoothing parameters (not default). See details.
`optim`	list of control parameters to pass to `optim` if this is used for outer estimation of smoothing parameters (not default). See details.
`newton`	list of control parameters to pass to default Newton optimizer used for outer estimation of log smoothing parameters. See details.
`outerPIsteps`	The number of performance interation steps used to initialize outer iteration.
`idLinksBases`	If smooth terms have their smoothing parameters linked via the `id` mechanism (see `s`), should they also have the same bases. Set this to `FALSE` only if you are sure you know what you are doing (you should almost surely set `scalePenalty` to `FALSE` as well in this case).
`scalePenalty`	`gamm` is somewhat sensitive to the absolute scaling of the penalty matrices of a smooth relative to its model matrix. This option rescales the penalty matrices to accomodate this problem. Probably should be set to `FALSE` if you are linking smoothing parameters but have set `idLinkBases` to `FALSE`.
`efs.lspmax`	maximum log smoothing parameters to allow under extended Fellner Schall smoothing parameter optimization.
`efs.tol`	change in REML to count as negligible when testing for EFS convergence. If the step is small and the last 3 steps led to a REML change smaller than this, then stop.
`keepData`	Should a copy of the original `data` argument be kept in the `gam` object? Strict compatibility with class `glm` would keep it, but it wastes space to do so.
`scale.est`	How to estimate the scale parameter for exponential family models estimated by outer iteration. See `gam.scale`.
`edge.correct`	With RE/ML smoothing parameter selection in `gam` using the default Newton RE/ML optimizer, it is possible to improve inference at the ‘completely smooth’ edge of the smoothing parameter space, by decreasing smoothing parameters until there is a small increase in the negative RE/ML (e.g. 0.02). Set to `TRUE` or to a number representing the target increase to use. Only changes the corrected smoothing parameter matrix, `Vc`.

Details

Outer iteration using newton is controlled by the list newton with the following elements: conv.tol (default 1e-6) is the relative convergence tolerance; maxNstep is the maximum length allowed for an element of the Newton search direction (default 5); maxSstep is the maximum length allowed for an element of the steepest descent direction (only used if Newton fails - default 2); maxHalf is the maximum number of step halvings to permit before giving up (default 30).

If outer iteration using nlm is used for fitting, then the control list nlm stores control arguments for calls to routine nlm. The list has the following named elements: (i) ndigit is the number of significant digits in the GCV/UBRE score - by default this is worked out from epsilon; (ii) gradtol is the tolerance used to judge convergence of the gradient of the GCV/UBRE score to zero - by default set to 10*epsilon; (iii) stepmax is the maximum allowable log smoothing parameter step - defaults to 2; (iv) steptol is the minimum allowable step length - defaults to 1e-4; (v) iterlim is the maximum number of optimization steps allowed - defaults to 200; (vi) check.analyticals indicates whether the built in exact derivative calculations should be checked numerically - defaults to FALSE. Any of these which are not supplied and named in the list are set to their default values.

Outer iteration using optim is controlled using list optim, which currently has one element: factr which takes default value 1e7.

Author(s)

Simon N. Wood [email protected]

References

Wood, S.N. (2011) Fast stable restricted maximum likelihood and marginal likelihood estimation of semiparametric generalized linear models. Journal of the Royal Statistical Society (B) 73(1):3-36

Wood, S.N. (2004) Stable and efficient multiple smoothing parameter estimation for generalized additive models. J. Amer. Statist. Ass.99:673-686.

https://www.maths.ed.ac.uk/~swood34/

gam.control Setting GAM fitting defaults