gamObject                package:mgcv                R Documentation

_F_i_t_t_e_d _g_a_m _o_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     A fitted GAM object returned by function 'gam' and of class
     '"gam"' inheriting from classes '"glm"' and '"lm"'. Method
     functions 'anova', 'logLik', 'influence', 'plot', 'predict',
     'print', 'residuals' and 'summary' exist for this class.

     All compulsory elements of '"glm"' and '"lm"' objects are present,
     but the fitting method for a GAM is different to a linear model or
     GLM, so that the elements relating to the QR decomposition of the
     model matrix are absent.

_V_a_l_u_e:

     A 'gam' object has the following elements:

     aic: AIC of the fitted model: bear in mind that the degrees of
          freedom used to calculate this are the effective degrees of
          freedom of the model, and the likelihood is evaluated at the
          maximum of the penalized likelihood in most cases, not at the
          MLE.

  assign: Array whose elements indicate which model term (listed in
          'pterms') each parameter relates to: applies only to
          non-smooth terms.

boundary: did parameters end up at boundary of parameter space?

    call: the matched call (allows 'update' to be used with 'gam'
          objects, for example). 

coefficients: the coefficients of the fitted model. Parametric
          coefficients are  first, followed  by coefficients for each
          spline term in turn.

 control: the 'gam' control list used in the fit.

converged: indicates whether or not the iterative fitting method
          converged.

    data: the original supplied data argument (for class '"glm"'
          compatibility).

deviance: model deviance (not penalized deviance).

 df.null: null degrees of freedom.

df.residual: effective residual degrees of freedom of the model.

     edf: estimated degrees of freedom for each model parameter.
          Penalization means that many of these are less than 1.

  family: family object specifying distribution and link used.

fit.method: Character string describing the multiple GCV/UBRE smoothing
          parameter estimation method used.

fitted.values: fitted model predictions of expected value for each
          datum.

 formula: the model formula.

full.formula: the model formula with each smooth term fully expanded
          and with option arguments given explicitly (i.e. not with
          reference to other variables) - useful for later prediction
          from the model.

gcv.ubre: The minimized GCV or UBRE score.

     hat: array of elements from the leading diagonal of the `hat' (or
          `influence') matrix.  Same length as response data vector.

    iter: number of iterations of P-IRLS taken to get convergence.

linear.predictors: fitted model prediction of link function of expected
          value for  each datum.

  method: One of '"GCV"' or '"UBRE"', depending on the fitting
          criterion used.

mgcv.conv: A list of convergence diagnostics relating to the '"mgcv"'
          or '"magic"' parts of smoothing parameter estimation - this
          will not be very meaningful for pure '"outer"' estimation of
          smoothing parameters. 'mgcv.conv' differs for method
          '"magic"' and '"mgcv"'. Here is  the '"mgcv"' version:

     _s_c_o_r_e corresponding to edf, an array of GCV or UBRE scores for the
          model given the final  estimated relative smoothing
          parameters.

     _g the gradient of the GCV/UBRE score w.r.t. the relative smoothing
          parameters at termination.

     _h the second derivatives corresponding to 'g' above - i.e. the
          leading diagonal of the Hessian.

     _e the eigen-values of the Hessian. All non-negative indicates a
          positive definite Hessian.

     _i_t_e_r the number of iterations taken.

     _i_n._o_k 'TRUE' if the second smoothing parameter guess improved the
          GCV/UBRE score.

     _s_t_e_p._f_a_i_l 'TRUE' if the algorithm terminated by failing to improve
          the GCV/UBRE score rather than by `converging'.  Not
          necessarily a problem, but check the above derivative
          information quite carefully.

          In the case of '"magic"' the items are:

     _f_u_l_l._r_a_n_k The apparent rank of the problem given the model matrix
          and  constraints.

     _r_a_n_k The numerical rank of the problem.

     _f_u_l_l_y._c_o_n_v_e_r_g_e_d 'TRUE' is multiple GCV/UBRE converged by meeting 
          convergence criteria. 'FALSE' if method stopped with a
          steepest descent step  failure.

     _h_e_s_s._p_o_s._d_e_f Was the hessian of the GCV/UBRE score positive
          definite at  smoothing parameter estimation convergence?

     _i_t_e_r How many iterations were required to find the smoothing
          parameters?

     _s_c_o_r_e._c_a_l_l_s and how many times did the GCV/UBRE score have to be
          evaluated?

     _r_m_s._g_r_a_d root mean square of the gradient of the GCV/UBRE score at
           convergence.

 min.edf: Minimum possible degrees of freedom for whole model.

   model: model frame containing all variables needed in original model
          fit.

na.action: The 'na.action' used in fitting.

    nsdf: number of parametric, non-smooth, model terms including the
          intercept.

null.deviance: deviance for single parameter model.

  offset: model offset.

outer.info: If `outer' iteration has been used to fit the model (see
          'gam.method') then this is present and contains whatever was
          returned by the optimization routine used (currently 'nlm' or
          'optim'). 

prior.weights: prior weights on observations.

  pterms: 'terms' object for strictly parametric part of model.

    rank: apparent rank of fitted model.

residuals: the working residuals for the fitted model.

    sig2: estimated or supplied variance/scale parameter.

  smooth: list of smooth objects, containing the basis information for
          each term in the  model formula in the order in which they
          appear. These smooth objects are what gets returned by the
          'smooth.construct' objects.

      sp: smoothing parameter for each smooth.

   terms: 'terms' object of 'model' model frame.

      Vp: estimated covariance matrix for the parameters. This is a
          Bayesian posterior covariance matrix that results from
          adopting a particular Bayesian model of the smoothing
          process. Paricularly useful for creating credible/confidence
          intervals.

      Ve: frequentist estimated covariance matrix for the parameter
          estimators. Particularly useful for testing whether terms are
          zero. Not so useful for CI's as smooths are usually biased.

 weights: final weights used in IRLS iteration.

       y: response data.

_W_A_R_N_I_N_G_S:

     This model object is different to that described in Chambers and
     Hastie (1993) in order to allow smoothing parameter estimation
     etc.

_A_u_t_h_o_r(_s):

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

_R_e_f_e_r_e_n_c_e_s:

     Key References on this implementation:

     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. (in press) Stable and efficient multiple smoothing
     parameter estimation for generalized additive models. J. Amer.
     Statist. Ass.

     Wood, S.N. (2004) On confidence intervals for GAMs based on
     penalized regression splines. Technical Report 04-12 Department of
     Statistics, University of Glasgow.

     Wood, S.N. (2006) Low rank scale invariant tensor product smooths
     for generalized additive mixed models. Biometrics.

     Key Reference on GAMs and related models:

     Hastie (1993) in Chambers and Hastie (1993) Statistical Models in
     S. Chapman and Hall.

     Hastie and Tibshirani (1990) Generalized Additive Models. Chapman
     and Hall.

     Wahba (1990) Spline Models of Observational Data. SIAM

_S_e_e _A_l_s_o:

     'gam'

