summary.gam               package:mgcv               R Documentation

Summary for a GAM fit

Description:

     Takes a fitted 'gam' object produced by 'gam()' and produces
     various useful summaries from it.

Usage:

     summary.gam(object,...)
     print.summary.gam(x,...)

Arguments:

  object: a fitted 'gam' object as produced by 'gam()'.

       x: a 'summary.gam' object produced by 'summary.gam()'.

     ...: other arguments.

Details:

     Model degrees of freedom are taken as the trace of the influence
     (or hat) matrix A for the model fit. Residual degrees of freedom
     are taken as number of data minus model degrees of freedom. Let
     P_i be the matrix  giving the parameters of the ith smooth when
     applied to the data (or pseudodata in the generalized case) and
     let X  be the design matrix of the model. Then tr(XP_i) is the edf
     for the ith term. Clearly this definition causes  the edf's to add
     up properly! 

     'print.summary.gam' tries to print various bits of summary
     information useful for term selection in a pretty way.

Value:

     'summary.gam' produces a list of summary information for a fitted
     'gam' object.  

 p.coeff: is an array of estimates of the strictly parametric model
          coefficients.

     p.t: is an array of the 'p.coeff''s divided by their standard
          errors.

    p.pv: is an array of p-values for the null hypothesis that the
          corresponding parameter is zero.  Calculated with reference
          to the t distribution with the estimated residual degrees of
          freedom for the model fit.

       m: The number of smooth terms in the model.

  chi.sq: An array of test statistics for assessing the significance of
          model smooth terms. If p_i  is the parameter vector for the
          ith smooth term, and this term has estimated covariance
          matrix V_i then the  statistic is p_i'V_i^{k-}p_i, where
          V_i^{k-} is the rank k-1  pseudo-inverse of V_i, and k is the
          basis dimension.

    s.pv: An array of approximate p-values for the null hypotheses that
          each smooth term is zero. Be warned, these are only 
          approximate. In the case in which UBRE has been used, they
          are obtained by comparing the chi.sq statistic given above to
          the  chi-squared distribution with degrees of  freedom given
          by the estimated degrees of freedom for the term. In the GCV
          case (in  which the scale parameter will have been estimated)
          the statistic is compared to an F distribution with upper
          d.f. given by the estimate degrees of freedom for the term,
          and lower d.f. given by the residual degrees of freedom for
          the model .  Use at your own risk! Typically the p-values
          will be somewhat inaccurate because they are conditional on
          the smoothing parameters and the distributional assumption
          doesn't have a firm theoretical basis.  A pragmatic approach
          to the latter issue is to check p-values by refitting the
          model using regression splines with each basis dimension set
          to one more than the rounded edf for the term (see example,
          below). In this latter case the distributional assumption
          would be fine if the smoothing parameters were known, but of
          course they are not, and conditioning on the smoothing
          parameters will always be problematic. The difficulty is that
          GCV has used the data to select the most plausible smoothing
          parameters for each term - not surprisingly this tends to
          mean that the terms appear a little more `significant' than
          they should. Of course this problem is no different to the
          standard difficulty in interpreting p-values for model terms
          when the model has been selected by hypothesis testing
          methods such as backwards elimination.    

      se: array of standard error estimates for all parameter
          estimates.

    r.sq: The adjusted r-squared for the model. Defined as the
          proportion of variance explained, where original variance and
           residual variance are both estimated using unbiased
          estimators. This quantity can be negative if your model is
          worse than a one  parameter constant model, and can be higher
          for the smaller of two nested models! Note that proportion
          null deviance  explained is probably more appropriate for
          non-normal errors.

dev.expl: The proportion of the null deviance explained by the model.

     edf: array of estimated degrees of freedom for the model terms.

residual.df: estimated residual degrees of freedom.

       n: number of data.

     gcv: minimized GCV score for the model, if GCV used.

    ubre: minimized UBRE score for the model, if UBRE used.

   scale: estimated (or given) scale parameter.

  family: the family used.

 formula: the original GAM formula.

WARNING:

     The supplied p-values are only approximate and should be treated
     with scepticism.

Author(s):

     Simon N. Wood simon@stats.gla.ac.uk

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

     <URL: http://www.stats.gla.ac.uk/~simon/>

See Also:

     'gam', 'predict.gam', 'gam.check'

Examples:

     library(mgcv)
     set.seed(0)
     n<-200
     sig2<-4
     x0 <- runif(n, 0, 1)
     x1 <- runif(n, 0, 1)
     x2 <- runif(n, 0, 1)
     x3 <- runif(n, 0, 1)
     pi <- asin(1) * 2
     y <- 2 * sin(pi * x0)
     y <- y + exp(2 * x1) - 3.75887
     y <- y + 0.2 * x2^11 * (10 * (1 - x2))^6 + 10 * (10 * x2)^3 * (1 - x2)^10 - 1.396
     e <- rnorm(n, 0, sqrt(abs(sig2)))
     y <- y + e
     b<-gam(y~s(x0)+s(x1)+s(x2)+s(x3))
     plot(b,pages=1)
     summary(b)
     # now check the p-values by using a pure regression spline.....
     b.d<-round(b$edf)+1 
     b.d<-pmax(b.d,3) # can't have basis dimension less than this!
     bc<-gam(y~s(x0,k=b.d[1],fx=TRUE)+s(x1,k=b.d[2],fx=TRUE)+
             s(x2,k=b.d[3],fx=TRUE)+s(x3,k=b.d[4],fx=TRUE))
     plot(bc,pages=1)
     summary(bc)
     # p-value check - increase k to make this useful!
     n<-200;p<-0;k<-20
     for (i in 1:k)
     { b<-gam(y~s(x,z),data=data.frame(y=rnorm(n),x=runif(n),z=runif(n)))
       p[i]<-summary(b)$s.p[1]
     }
     plot(((1:k)-0.5)/k,sort(p))

