plot.gam                package:mgcv                R Documentation

Default GAM plotting

Description:

     Takes a fitted 'gam' object produced by 'gam()' and plots the 
     component smooth functions that make it up, on the scale of the
     linear predictor.

Usage:

     plot.gam(x,residuals=FALSE,rug=TRUE,se=TRUE,pages=0,select=NULL,
              scale=-1,n=100,n2=40,pers=FALSE,theta=30,phi=30,jit=FALSE,
              xlab=NULL,ylab=NULL,main=NULL,ylim=NULL,xlim=NULL,too.far=0.1,...)

Arguments:

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

residuals: If 'TRUE' then partial residuals are added to plots of 1-D
          smooths. If 'FALSE'  then no residuals are added. If this is
          an array of the correct length then it is used as the array
          of  residuals to be used for producing partial residuals. If
          'TRUE' then the residuals are the working residuals from the
          IRLS iteration weighted by the IRLS weights. Partial
          residuals for a smooth term are the residuals that would be
          obtained by dropping the term concerned from the model, while
          leaving all other  estimates fixed (i.e. the estimates for
          the term plus the residuals).

     rug: when TRUE (default) then the covariate to which the plot
          applies is displayed as a rug plot at the foot of each plot
          of a 1-d smooth, and the locations of the covariates are
          plotted as points on the contour plot representing a 2-d
          smooth.

      se: when TRUE (default) upper and lower lines are added to the
          1-d plots at 2 standard errors above and below the estimate
          of the smooth being plotted while for 2-d plots, surfaces at
          +1 and -1 standard errors are contoured and overlayed on the
          contour plot for the estimate. If a positive number is
          supplied then this number is multiplied by the standard
          errors when calculating standard error curves or surfaces.

   pages: (default 0) the number of pages over which to spread the
          output. For example,  if 'pages=1' then all terms will be
          plotted on one page with the layout performed automatically. 
          Set to 0 to have the routine leave all graphics settings as
          they are. 

  select: Allows the  plot for a single model term to be selected for
          printing. e.g. if you just want the plot for the second
          smooth term set 'select=2'. 

   scale: set to -1 (default) to have the same y-axis scale for each
          plot, and to 0 for a  different y axis for each plot. Ignored
          if 'ylim' supplied.

       n: number of points used for each 1-d plot - for a nice smooth
          plot this needs to be several times the estimated  degrees of
          freedom for the smooth. Default value 100.

      n2: Square root of number of points used to grid estimates of 2-d
          functions for contouring.

    pers: Set to 'TRUE' if you want perspective plots for 2-d terms.

   theta: One of the perspective plot angles.

     phi: The other perspective plot angle.

     jit: Set to TRUE if you want rug plots for 1-d terms to be
          jittered.

    xlab: If supplied then this will be used as the x label for all
          plots.

    ylab: If supplied then this will be used as the y label for all
          plots.

    main: Used as title (or z axis label) for plots if supplied.

    ylim: If supplied then this pair of numbers are used as the y
          limits for each plot.

    xlim: If supplied then this pair of numbers are used as the x
          limits for each plot.

 too.far: If greater than 0 then this is used to determine when a
          location is too far from data to be plotted when plotting 2-D
          smooths. This is useful since smooths tend to go wild away
          from data. The data are scaled into the unit square before
          deciding what to exclude, and 'too.far' is a distance  within
          the unit square.

     ...: other graphics parameters to pass on to plotting commands.

Details:

     Produces default plot showing the smooth components of a fitted
     GAM.

     For plots of 1-d smooths, the x axis of each plot is labelled 
     with the covariate name, while the y axis is labelled 's(cov,edf)
     ' where 'cov' is the covariate name, and 'edf' the estimated (or
     user defined for regression splines) degrees of freedom of the
     smooth.

     Contour plots are produced for 2-d smooths with the x-axes
     labelled with the first covariate name and the y axis with the
     second covariate name. The main title of the plot is something
     like 's(var1,var2,edf)', indicating the variables of which the
     term is a function, and the estimated degrees of freedom for the
     term. When 'se=TRUE', estimator variability is shown by overlaying
     contour plots at plus and minus 1 s.e. relative to the main
     estimate. If 'se' is a positive number then contour plots are at
     plus or minus 'se' multiplied by the s.e. Contour levels are
     chosen to try and ensure reasonable separation of the contours of
     the different plots, but this is not always easy to achieve. Note
     that these plots can not be modified to the same extent as the
     other plot. 

     Within the function, the data for the plots is obtained by direct
     calls to the compiled C code that 'predict.gam' uses.   

     Smooths of more than 2 variables are not currently dealt with, but
     simply generate a warning, but see 'vis.gam'.

Value:

     The function simply generates plots.

WARNING:

     Note that the behaviour of this function is not identical to 
     'plot.gam()' in S-PLUS.

     Plots of 2-D smooths with standard error contours shown can not
     easily be customized.

     The function can not deal with smooths of more than 2 variables!

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

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,residuals=TRUE)
     # example with 2-d plots
     b1<-gam(y~s(x0,x1)+s(x2)+s(x3))
     op<-par(mfrow=c(2,2))
     plot(b1)
     par(op) 

