gam.control.Rd 5.93 KB
 Dirk Eddelbuettel committed Apr 10, 2018 1 2 3 4 5 6 7 8 \name{gam.control} \alias{gam.control} %- Also NEED an \alias' for EACH other topic documented here. \title{Setting GAM fitting defaults} \description{ This is an internal function of package \code{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  Dirk Eddelbuettel committed Apr 10, 2018 9 loss of numerical stability during fitting. To change the default  Dirk Eddelbuettel committed Apr 10, 2018 10 choise of fitting method, see \code{\link{gam}} arguments \code{method} and \code{optimizer}.  Dirk Eddelbuettel committed Apr 10, 2018 11 12 } \usage{  Dirk Eddelbuettel committed Apr 10, 2018 13 14 15 gam.control(irls.reg=0.0,epsilon = 1e-06, maxit = 100, mgcv.tol=1e-7,mgcv.half=15, trace = FALSE, rank.tol=.Machine\$double.eps^0.5,  Dirk Eddelbuettel committed Apr 10, 2018 16  nlm=list(),optim=list(),newton=list(),  Dirk Eddelbuettel committed Apr 10, 2018 17  outerPIsteps=0,idLinksBases=TRUE,scalePenalty=TRUE,  Dirk Eddelbuettel committed Apr 10, 2018 18  keepData=FALSE)  Dirk Eddelbuettel committed Apr 10, 2018 19 20 } \arguments{  Dirk Eddelbuettel committed Apr 10, 2018 21   Dirk Eddelbuettel committed Apr 10, 2018 22 23 24 25 26 27 \item{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  Dirk Eddelbuettel committed Apr 10, 2018 28 \code{irls.reg} is the size of the penalty.  Dirk Eddelbuettel committed Apr 10, 2018 29 30 }  Dirk Eddelbuettel committed Apr 10, 2018 31 \item{epsilon}{This is used for judging conversion of the GLM IRLS loop in  Dirk Eddelbuettel committed Apr 10, 2018 32 \code{\link{gam.fit}} or \code{\link{gam.fit3}}.}  Dirk Eddelbuettel committed Apr 10, 2018 33   Dirk Eddelbuettel committed Apr 10, 2018 34 \item{maxit}{Maximum number of IRLS iterations to perform.}  Dirk Eddelbuettel committed Apr 10, 2018 35 36 37 38 39 40 41 42 43 44 45  \item{mgcv.tol}{The convergence tolerance parameter to use in GCV/UBRE optimization.} \item{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.} \item{trace}{Set this to \code{TRUE} to turn on diagnostic output.}  Dirk Eddelbuettel committed Apr 10, 2018 46 47 48 49 \item{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 \code{\link{mgcv}}).}  Dirk Eddelbuettel committed Apr 10, 2018 50 \item{nlm}{list of control parameters to pass to \code{\link{nlm}} if this is  Dirk Eddelbuettel committed Apr 10, 2018 51 used for outer estimation of smoothing parameters (not default). See details.}  Dirk Eddelbuettel committed Apr 10, 2018 52 53  \item{optim}{list of control parameters to pass to \code{\link{optim}} if this  Dirk Eddelbuettel committed Apr 10, 2018 54 is used for outer estimation of smoothing parameters (not default). See details.}  Dirk Eddelbuettel committed Apr 10, 2018 55 56 57  \item{newton}{list of control parameters to pass to default Newton optimizer used for outer estimation of log smoothing parameters. See details.}  Dirk Eddelbuettel committed Apr 10, 2018 58 59  \item{outerPIsteps}{The number of performance interation steps used to  Dirk Eddelbuettel committed Apr 10, 2018 60 initialize outer iteration.}  Dirk Eddelbuettel committed Apr 10, 2018 61 62 63 64 65 66 67 68 69 70 71  \item{idLinksBases}{If smooth terms have their smoothing parameters linked via the \code{id} mechanism (see \code{\link{s}}), should they also have the same bases. Set this to \code{FALSE} only if you are sure you know what you are doing (you should almost surely set \code{scalePenalty} to \code{FALSE} as well in this case).} \item{scalePenalty}{\code{\link{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 \code{FALSE} if you are linking smoothing parameters but have set \code{idLinkBases} to \code{FALSE}.}  Dirk Eddelbuettel committed Apr 10, 2018 72 73 74 75  \item{keepData}{Should a copy of the original \code{data} argument be kept in the \code{gam} object? Strict compatibility with class \code{glm} would keep it, but it wastes space to do so. }  Dirk Eddelbuettel committed Apr 10, 2018 76 77 }  Dirk Eddelbuettel committed Apr 10, 2018 78 79 80 81 82 83 84 85 \details{ Outer iteration using \code{newton} is controlled by the list \code{newton} with the following elements: \code{conv.tol} (default 1e-6) is the relative convergence tolerance; \code{maxNstep} is the maximum length allowed for an element of the Newton search direction (default 5); \code{maxSstep} is the maximum length allowed for an element of the steepest descent direction (only used if Newton fails - default 2); \code{maxHalf} is  Dirk Eddelbuettel committed Apr 10, 2018 86 the maximum number of step halvings to permit before giving up (default 30).  Dirk Eddelbuettel committed Apr 10, 2018 87 88  If outer iteration using \code{\link{nlm}} is used for fitting, then the control list  Dirk Eddelbuettel committed Apr 10, 2018 89 90 91 92 93 \code{nlm} stores control arguments for calls to routine \code{\link{nlm}}. The list has the following named elements: (i) \code{ndigit} is the number of significant digits in the GCV/UBRE score - by default this is worked out from \code{epsilon}; (ii) \code{gradtol} is the tolerance used to judge convergence of the gradient of the GCV/UBRE score to zero - by default  Dirk Eddelbuettel committed Apr 10, 2018 94 set to \code{10*epsilon}; (iii) \code{stepmax} is the maximum allowable log  Dirk Eddelbuettel committed Apr 10, 2018 95 96 97 98 99 100 101 102 103 104 105 smoothing parameter step - defaults to 2; (iv) \code{steptol} is the minimum allowable step length - defaults to 1e-4; (v) \code{iterlim} is the maximum number of optimization steps allowed - defaults to 200; (vi) \code{check.analyticals} indicates whether the built in exact derivative calculations should be checked numerically - defaults to \code{FALSE}. Any of these which are not supplied and named in the list are set to their default values. Outer iteration using \code{\link{optim}} is controlled using list \code{optim}, which currently has one element: \code{factr} which takes default value 1e7.  Dirk Eddelbuettel committed Apr 10, 2018 106 107 108 109 110 } \references{  Dirk Eddelbuettel committed Apr 10, 2018 111 112 113 114 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  Dirk Eddelbuettel committed Apr 10, 2018 115 Wood, S.N. (2004) Stable and efficient multiple smoothing parameter estimation for  Dirk Eddelbuettel committed Apr 10, 2018 116 117 generalized additive models. J. Amer. Statist. Ass.99:673-686.  Dirk Eddelbuettel committed Apr 10, 2018 118   Dirk Eddelbuettel committed Apr 10, 2018 119 \url{http://www.maths.bath.ac.uk/~sw283/}  Dirk Eddelbuettel committed Apr 10, 2018 120 121 122  }  Dirk Eddelbuettel committed Apr 10, 2018 123 \author{ Simon N. Wood \email{simon.wood@r-project.org}}  Dirk Eddelbuettel committed Apr 10, 2018 124 125   Dirk Eddelbuettel committed Apr 10, 2018 126 \seealso{\code{\link{gam}}, \code{\link{gam.fit}}, \code{\link{glm.control}} }  Dirk Eddelbuettel committed Apr 10, 2018 127 128 129 130 131 132  \keyword{models} \keyword{smooth} \keyword{regression}%-- one or more .. `