R: Setting GAM fitting defaults

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.method.

Usage

gam.control(irls.reg=0.0,epsilon = 1e-06, maxit = 100,globit = 20,
            mgcv.tol=1e-7,mgcv.half=15,nb.theta.mult=10000, trace = FALSE,
            rank.tol=.Machine$double.eps^0.5,absorb.cons=TRUE,
            max.tprs.knots=5000,nlm=list(),optim=list(),
            outerPIsteps=4)

Arguments

`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. The penalty can not be used if the underlying fitting method is `mgcv` (not the default - see `gam.method` for details).
`epsilon`	This is used for judging conversion of the GLM IRLS loop in `gam.fit` or `gam.fit2` .
`maxit`	Maximum number of IRLS iterations to perform using cautious GCV/UBRE optimization, after `globit` IRLS iterations with normal GCV optimization have been performed. Note that only fitting based on `mgcv` (not default) makes any distinction between cautious and global optimization.
`globit`	Maximum number of IRLS iterations to perform with normal GCV/UBRE optimization. If convergence is not achieved after these iterations then a further `maxit` iterations will be performed using cautious GCV/UBRE optimization.
`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.
`nb.theta.mult`	Controls the limits on theta when negative binomial parameter is to be estimated. Maximum theta is set to the initial value multiplied by `nb.theta.mult`, while the minimum value is set to the initial value divided by `nb.theta.mult`.
`trace`	Set this to `TRUE` to turn on diagnostic output.
`rank.tol`	The tolerance used to estimate the rank of the fitting problem, for methods which deal with rank deficient cases (basically all except those based on `mgcv`).
`absorb.cons`	If `TRUE` then the GAM is set up using a parameterization which requires no further constraint. Usually this means that all the smooths are automatically centered (i.e. they sum to zero over the covariate values). If `FALSE` then the ordinary parameterizations of the smooths are used, which require constraints to be imposed during fitting.
`max.tprs.knots`	This is the default initial maximum number of knots to allow when constructing a t.p.r.s bases (`bs="tp"`). The set up cost (and storage) for these smooths scales as the square of the number of initial knots, so if it's too high you can appear to freeze R. Usually one would want to use an alternative smoothing basis (or `te` terms), or the approach illustrated in the examples in `gam`, rather than simply increasing this default.
`nlm`	list of control parameters to pass to `nlm` if this is used for outer estimation of smoothing parameters. See details.
`optim`	list of control parameters to pass to `optim` if this is used for outer estimation of smoothin parameters. See details.
`outerPIsteps`	The number of performance interation steps used to initialize outer iteration. Less than 1 means that only one performance iteration step is taken to get the function scale, but the corresponding smoothing parameter estimates are discarded.

Details

When outer iteration 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 100*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.

When fitting is been done by calls to routine mgcv, maxit and globit control the maximum iterations of the IRLS algorithm, as follows: the algorithm will first execute up to globit steps in which the GCV/UBRE algorithm performs a global search for the best overall smoothing parameter at every iteration. If convergence is not achieved within globit iterations, then a further maxit steps are taken, in which the overall smoothing parameter estimate is taken as the one locally minimising the GCV/UBRE score and resulting in the lowest EDF change. The difference between the two phases is only significant if the GCV/UBRE function develops more than one minima. The reason for this approach is that the GCV/UBRE score for the IRLS problem can develop `phantom' minimima for some models: these are minima which are not present in the GCV/UBRE score of the IRLS problem resulting from moving the parameters to the minimum! Such minima can lead to convergence failures, which are usually fixed by the second phase.

Author(s)

Simon N. Wood simon.wood@r-project.org

References

Gu and Wahba (1991) Minimizing GCV/GML scores with multiple smoothing parameters via the Newton method. SIAM J. Sci. Statist. Comput. 12:383-398

Wood, S.N. (2000) Modelling and Smoothing Parameter Estimation with Multiple Quadratic Penalties. J.R.Statist.Soc.B 62(2):413-428

Wood, S.N. (2003) Thin plate regression splines. J.R.Statist.Soc.B 65(1):95-114

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

http://www.stats.gla.ac.uk/~simon/