summary.gam {mgcv}  R Documentation 
Summary for a GAM fit
Description
Takes a fitted gam
object produced by gam()
and produces various useful
summaries from it. (See sink
to divert output to a file.)
Usage
## S3 method for class 'gam'
summary(object, dispersion=NULL, freq=FALSE, re.test=TRUE, ...)
## S3 method for class 'summary.gam'
print(x,digits = max(3, getOption("digits")  3),
signif.stars = getOption("show.signif.stars"),...)
Arguments
object 
a fitted 
x 
a 
dispersion 
A known dispersion parameter. 
freq 
By default pvalues for parametric terms are calculated using the Bayesian estimated
covariance matrix of the parameter estimators. If this is set to 
re.test 
Should tests be performed for random effect terms (including any term with a zero dimensional null space)? For large models these tests can be computationally expensive. 
digits 
controls number of digits printed in output. 
signif.stars 
Should significance stars be printed alongside output. 
... 
other arguments. 
Details
Model degrees of freedom are taken as the trace of the influence (or
hat) matrix {\bf A}
for the model fit.
Residual degrees of freedom are taken as number of data minus model degrees of
freedom.
Let {\bf 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 {\bf X}
be the design matrix of the model. Then tr({\bf XP}_i )
is the edf for the ith term. Clearly this
definition causes the edf's to add up properly! An alternative version of EDF is more appropriate for pvalue computation, and is based on the trace of 2{\bf A}  {\bf AA}
.
print.summary.gam
tries to print various bits of summary information useful for term selection in a pretty way.
Pvalues for smooth terms are usually based on a test statistic motivated by an extension of Nychka's (1988) analysis of the frequentist properties of Bayesian confidence intervals for smooths (Marra and Wood, 2012). These have better frequentist performance (in terms of power and distribution under the null) than the alternative strictly frequentist approximation. When the Bayesian intervals have good across the function properties then the pvalues have close to the correct null distribution and reasonable power (but there are no optimality results for the power). Full details are in Wood (2013b), although what is computed is actually a slight variant in which the components of the test statistic are weighted by the iterative fitting weights.
Note that for terms with no unpenalized terms (such as Gaussian random effects) the Nychka (1988) requirement for smoothing bias to be substantially less than variance breaks down (see e.g. appendix of Marra and Wood, 2012), and this results in incorrect null distribution for pvalues computed using the above approach. In this case it is necessary to use an alternative approach designed for random effects variance components, and this is done. See Wood (2013a) for details: the test is based on a likelihood ratio statistic (with the reference distribution appropriate for the null hypothesis on the boundary of the parameter space).
All pvalues are computed without considering uncertainty in the smoothing parameter estimates.
In simulations the pvalues have best behaviour under ML smoothness selection, with REML coming second. In general the pvalues behave well, but neglecting smoothing parameter uncertainty means that they may be somewhat too low when smoothing parameters are highly uncertain. High uncertainty happens in particular when smoothing parameters are poorly identified, which can occur with nested smooths or highly correlated covariates (high concurvity).
By default the pvalues for parametric model terms are also based on Wald tests using the Bayesian
covariance matrix for the coefficients. This is appropriate when there are "re" terms present, and is
otherwise rather similar to the results using the frequentist covariance matrix (freq=TRUE
), since
the parametric terms themselves are usually unpenalized. Default Pvalues for parameteric terms that are
penalized using the paraPen
argument will not be good. However if such terms represent conventional
random effects with full rank penalties, then setting freq=TRUE
is appropriate.
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.pv 
is an array of pvalues 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 if the dispersion parameter has been estimated, and the standard normal if not. 
m 
The number of smooth terms in the model. 
chi.sq 
An array of test statistics for assessing the significance of model smooth terms. See details. 
s.pv 
An array of approximate pvalues for the null hypotheses that each smooth term is zero. Be warned, these are only approximate. 
se 
array of standard error estimates for all parameter estimates. 
r.sq 
The adjusted rsquared 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! The proportion null deviance
explained is probably more appropriate for nonnormal errors. Note that 
dev.expl 
The proportion of the null deviance explained by the model. The null deviance is computed taking account of any offset, so

edf 
array of estimated degrees of freedom for the model terms. 
residual.df 
estimated residual degrees of freedom. 
n 
number of data. 
np 
number of model coefficients (regression coefficients, not smoothing parameters or other parameters of likelihood). 
rank 
apparent model rank. 
method 
The smoothing selection criterion used. 
sp.criterion 
The minimized value of the smoothness selection criterion. Note that for ML and REML methods, what is reported is the negative log marginal likelihood or negative log restricted likelihood. 
scale 
estimated (or given) scale parameter. 
family 
the family used. 
formula 
the original GAM formula. 
dispersion 
the scale parameter. 
pTerms.df 
the degrees of freedom associated with each parametric term (excluding the constant). 
pTerms.chi.sq 
a Wald statistic for testing the null hypothesis that the each parametric term is zero. 
pTerms.pv 
pvalues associated with the tests that each term is zero. For penalized fits these are approximate. The reference distribution is an appropriate chisquared when the scale parameter is known, and is based on an F when it is not. 
cov.unscaled 
The estimated covariance matrix of the parameters (or
estimators if 
cov.scaled 
The estimated covariance matrix of the parameters
(estimators if 
p.table 
significance table for parameters 
s.table 
significance table for smooths 
p.Terms 
significance table for parametric model terms 
WARNING
The pvalues are approximate and neglect smoothing parameter uncertainty. They are likely to be somewhat too low when smoothing parameter estimates are highly uncertain: do read the details section. If the exact values matter, read Wood (2013a or b).
Pvalues for terms penalized via ‘paraPen’ are unlikely to be correct.
Author(s)
Simon N. Wood simon.wood@rproject.org with substantial improvements by Henric Nilsson.
References
Marra, G and S.N. Wood (2012) Coverage Properties of Confidence Intervals for Generalized Additive Model Components. Scandinavian Journal of Statistics, 39(1), 5374. doi:10.1111/j.14679469.2011.00760.x
Nychka (1988) Bayesian Confidence Intervals for Smoothing Splines. Journal of the American Statistical Association 83:11341143.
Wood, S.N. (2013a) A simple test for random effects in regression models. Biometrika 100:10051010 doi:10.1093/biomet/ast038
Wood, S.N. (2013b) On pvalues for smooth components of an extended generalized additive model. Biometrika 100:221228 doi:10.1093/biomet/ass048
Wood S.N. (2017) Generalized Additive Models: An Introduction with R (2nd edition). Chapman and Hall/CRC Press. doi:10.1201/9781315370279
See Also
gam
, predict.gam
,
gam.check
, anova.gam
, gam.vcomp
, sp.vcov
Examples
library(mgcv)
set.seed(0)
dat < gamSim(1,n=200,scale=2) ## simulate data
b < gam(y~s(x0)+s(x1)+s(x2)+s(x3),data=dat)
plot(b,pages=1)
summary(b)
## now check the pvalues by using a pure regression spline.....
b.d < round(summary(b)$edf)+1 ## get edf per smooth
b.d < pmax(b.d,3) # can't have basis dimension less than 3!
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),data=dat)
plot(bc,pages=1)
summary(bc)
## Example where some pvalues are less reliable...
dat < gamSim(6,n=200,scale=2)
b < gam(y~s(x0,m=1)+s(x1)+s(x2)+s(x3)+s(fac,bs="re"),data=dat)
## Here s(x0,m=1) can be penalized to zero, so pvalue approximation
## cruder than usual...
summary(b)
## pvalue check  increase k to make this useful!
k<20;n < 200;p < rep(NA,k)
for (i in 1:k)
{ b<gam(y~te(x,z),data=data.frame(y=rnorm(n),x=runif(n),z=runif(n)),
method="ML")
p[i]<summary(b)$s.p[1]
}
plot(((1:k)0.5)/k,sort(p))
abline(0,1,col=2)
ks.test(p,"punif") ## how close to uniform are the pvalues?
## A Gamma example, by modify `gamSim' output...
dat < gamSim(1,n=400,dist="normal",scale=1)
dat$f < dat$f/4 ## true linear predictor
Ey < exp(dat$f);scale < .5 ## mean and GLM scale parameter
## Note that `shape' and `scale' in `rgamma' are almost
## opposite terminology to that used with GLM/GAM...
dat$y < rgamma(Ey*0,shape=1/scale,scale=Ey*scale)
bg < gam(y~ s(x0)+ s(x1)+s(x2)+s(x3),family=Gamma(link=log),
data=dat,method="REML")
summary(bg)