gam.fit3                package:mgcv                R Documentation

_P-_I_R_L_S _G_A_M _e_s_t_i_m_a_t_i_o_n _w_i_t_h _G_C_V & _U_B_R_E/_A_I_C _o_r _R_E/_M_L _d_e_r_i_v_a_t_i_v_e _c_a_l_c_u_l_a_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     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
     'gam'.

_U_s_a_g_e:

     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)),...) 

_A_r_g_u_m_e_n_t_s:

       x: The model matrix for the GAM (or any penalized GLM).

       y: The response variable.

      sp: The log smoothing parameters.

      Eb: A balanced version of the total penalty matrix: usd for
          numerical rank determination.

     UrS: List of square root penalties premultiplied by transpose of
          orthogonal basis for the total penalty.

 weights: prior weights for fitting.

   start: optional starting parameter guesses.

etastart: optional starting values for the linear predictor.

 mustart: optional starting values for the mean.

  offset: the model offset

      U1: An orthogonal basis for the range space of the penalty -
          required for ML smoothness estimation only.

      Mp: The dimension of the total penalty null space - required for
          ML smoothness estimation only.

  family: the family - actually this routine would never be called with
          'gaussian()'

 control: control list as returned from 'glm.control'

intercept: does the model have and intercept, 'TRUE' or 'FALSE'

   deriv: Should derivatives of the GCV and UBRE/AIC scores be
          calculated? 0, 1 or 2, indicating the maximum order of
          differentiation to apply.

   gamma: The weight given to each degree of freedom in the GCV and
          UBRE scores can be varied (usually increased) using this
          parameter.

   scale: The scale parameter - needed for the UBRE/AIC score.

printWarn: Set to '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.

scoreType: specifies smoothing parameter selection criterion to use.

null.coef: coefficients for a model which gives some sort of upper
          bound on deviance. This allows immediate divergence problems
          to be controlled.

     ...: Other arguments: ignored.

_D_e_t_a_i_l_s:

     This routine is basically '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 'fix.family.link'.

_A_u_t_h_o_r(_s):

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

     The routine has been modified from 'glm.fit' in R 2.0.1, written
     by the R core (see 'glm.fit' for further credits).

_R_e_f_e_r_e_n_c_e_s:

     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/>

_S_e_e _A_l_s_o:

     'gam.fit',  'gam', 'mgcv', 'magic'