\HeaderA{gam.fit3}{P-IRLS GAM estimation with GCV \& UBRE/AIC or RE/ML derivative calculation}{gam.fit3}
\keyword{models}{gam.fit3}
\keyword{smooth}{gam.fit3}
\keyword{regression}{gam.fit3}
\begin{Description}\relax
Estimation of GAM smoothing parameters is most stable if
optimization of the UBRE/AIC, GCV, GACV, REML or ML score is outer to the penalized iteratively
re-weighted least squares scheme used to estimate the model given smoothing 
parameters.

This routine estimates a GAM (any quadratically penalized GLM) given log 
smoothing paramaters, and evaluates derivatives of the smoothness selection scores 
of the model with respect to the
log smoothing parameters. Calculation of exact derivatives is generally faster
than approximating them by finite differencing, as well as generally improving
the reliability of GCV/UBRE/AIC/REML score minimization.

The approach is to run the P-IRLS
to convergence, and only then to iterate for first and second derivatives. 

Not normally called directly, but rather service routines for \code{\LinkA{gam}{gam}}.
\end{Description}
\begin{Usage}
\begin{verbatim}

gam.fit3(x, y, sp, Eb ,UrS=list(), 
         weights = rep(1, nobs), start = NULL, etastart = NULL, 
         mustart = NULL, offset = rep(0, nobs), U1 = diag(ncol(x)), 
         Mp = -1, family = gaussian(), control = gam.control(), 
         intercept = TRUE,deriv=2,gamma=1,scale=1,
         printWarn=TRUE,scoreType="REML",null.coef=rep(0,ncol(x)),...) 
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] The model matrix for the GAM (or any penalized GLM).
\item[\code{y}] The response variable.
\item[\code{sp}] The log smoothing parameters.
\item[\code{Eb}] A balanced version of the total penalty matrix: usd for numerical rank determination.
\item[\code{UrS}] List of square root penalties premultiplied by transpose of orthogonal
basis for the total penalty.
\item[\code{weights}] prior weights for fitting.
\item[\code{start}] optional starting parameter guesses.
\item[\code{etastart}] optional starting values for the linear predictor.
\item[\code{mustart}] optional starting values for the mean.
\item[\code{offset}] the model offset
\item[\code{U1}] An orthogonal basis for the range space of the penalty --- required for ML smoothness estimation only.
\item[\code{Mp}] The dimension of the total penalty null space --- required for ML smoothness estimation only.
\item[\code{family}] the family - actually this routine would never be called with \code{gaussian()}
\item[\code{control}] control list as returned from \code{\LinkA{glm.control}{glm.control}}
\item[\code{intercept}] does the model have and intercept, \code{TRUE} or
\code{FALSE}
\item[\code{deriv}] Should derivatives of the GCV and UBRE/AIC scores be calculated?
0, 1 or 2,
indicating the maximum order of differentiation to apply.
\item[\code{gamma}] The weight given to each degree of freedom in the GCV and UBRE
scores can be varied (usually increased) using this parameter.
\item[\code{scale}] The scale parameter - needed for the UBRE/AIC score.
\item[\code{printWarn}] Set to \code{FALSE} to suppress some warnings. Useful in
order to ensure that some warnings are only printed if they apply to the final
fitted model, rather than an intermediate used in optimization.
\item[\code{scoreType}] specifies smoothing parameter selection criterion to use.
\item[\code{null.coef}] coefficients for a model which gives some sort of upper bound on deviance.
This allows immediate divergence problems to be controlled.
\item[\code{...}] Other arguments: ignored.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This routine is basically \code{\LinkA{glm.fit}{glm.fit}} with some
modifications to allow (i) for quadratic penalties on the log likelihood;
(ii) derivatives of the model coefficients with respect to
log smoothing parameters to be obtained by use of the implicit function theorem and 
(iii) derivatives of the GAM GCV, UBRE/AIC, REML or ML scores to be
evaluated at convergence. 

In addition the routines apply step halving to any step that increases the
penalized deviance substantially.

The most costly parts of the calculations are performed by calls to compiled C
code (which in turn calls LAPACK routines) in place of the compiled code that
would usually perform least squares estimation on the working model in the
IRLS iteration. 

Estimation of smoothing parameters by optimizing GCV scores obtained at
convergence of the P-IRLS iteration was proposed by O'Sullivan et al. (1986),
and is here termed `outer' iteration. 

Note that use of non-standard families with this routine requires modification
of the families as described in \code{\LinkA{fix.family.link}{fix.family.link}}.
\end{Details}
\begin{Author}\relax
Simon N. Wood \email{simon.wood@r-project.org}

The routine has been modified from \code{glm.fit} in R 2.0.1, written
by the R core (see \code{\LinkA{glm.fit}{glm.fit}} for further credits).
\end{Author}
\begin{References}\relax
O 'Sullivan, Yandall \& Raynor (1986) Automatic smoothing of regression
functions in generalized linear models. J. Amer. Statist. Assoc. 81:96-103.

Wood, S.N. (2008) Fast stable direct fitting and smoothness selection for
generalized additive models. J.R.Statist. Soc. B 70(3):495-518


\url{http://www.maths.bath.ac.uk/~sw283/}
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{gam.fit}{gam.fit}},  \code{\LinkA{gam}{gam}}, \code{\LinkA{mgcv}{mgcv}}, \code{\LinkA{magic}{magic}}
\end{SeeAlso}

