gam.control {mgcv}  R Documentation 
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,ncv.threads=1,irls.reg=0.0,epsilon = 1e07,
maxit = 200,mgcv.tol=1e7,mgcv.half=15, trace = FALSE,
rank.tol=.Machine$double.eps^0.5,nlm=list(),
optim=list(),newton=list(),
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 
ncv.threads 
The computations for neighbourhood crossvalidation (NCV) typically scale better than the rest of the GAM computations and are worth parallelizing. 
irls.reg 
For most models this should be 0. The iteratively reweighted 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

epsilon 
This is used for judging conversion of the GLM IRLS loop in

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 
rank.tol 
The tolerance used to estimate the rank of the fitting problem. 
nlm 
list of control parameters to pass to 
optim 
list of control parameters to pass to 
newton 
list of control parameters to pass to default Newton optimizer used for outer estimation of log smoothing parameters. See details. 
idLinksBases 
If smooth terms have their smoothing parameters linked via
the 
scalePenalty 

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 
scale.est 
How to estimate the scale parameter for exponential family models estimated
by outer iteration. See 
edge.correct 
With RE/ML smoothing parameter selection in 
Details
Outer iteration using newton
is controlled by the list newton
with the following elements: conv.tol
(default
1e6) 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 1e4; (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 simon.wood@rproject.org
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):336
Wood, S.N. (2004) Stable and efficient multiple smoothing parameter estimation for generalized additive models. J. Amer. Statist. Ass.99:673686.
https://www.maths.ed.ac.uk/~swood34/