gam.control: Setting GAM fitting defaults
In mgcv: Mixed GAM Computation Vehicle with Automatic Smoothness Estimation
gam.control 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 = 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(),
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.
ncv.threads
The computations for neighbourhood cross-validation (NCV) typically scale better than the rest of the GAM computations and are worth parallelizing. ncv.threads allows you to set the number of theads to use separately.
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.
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 simon.wood@r-project.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):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/
See Also
gam, gam.fit, glm.control
mgcv documentation built on May 29, 2024, 4:34 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| gam.control | 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 = 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(),
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 cross-validation (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 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
|
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
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 simon.wood@r-project.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):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/
See Also
gam, gam.fit, glm.control
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.