plot.gam                package:mgcv                R Documentation

_D_e_f_a_u_l_t _G_A_M _p_l_o_t_t_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     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. Optionally produces term plots for parametric
     model components as well.

_U_s_a_g_e:

     ## S3 method for class 'gam':
     plot(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,
              all.terms=FALSE,shade=FALSE,shade.col="gray80",
              shift=0,trans=I,...)

_A_r_g_u_m_e_n_t_s:

       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.
          See also 'shade', below. 

   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.

all.terms: if set to 'TRUE' then the partial effects of parametric
          model components are also plotted, via a call to 'termplot'.
          Only terms of order 1 can be plotted in this way.

   shade: Set to 'TRUE' to produce shaded regions as confidence bands
          for smooths (not avaliable for parametric terms, which are
          plotted using 'termplot').

shade.col: define the color used for shading confidence bands.

   shift: constant to add to each smooth (on the scale of the linear
          predictor) before plotting. Can be useful for some
          diagnostics, or with 'trans'.

   trans: function to apply to each smooth  (after any shift), before
          plotting. 'shift' and 'trans' are occasionally useful as a
          means for getting plots on the response scale, when the model
          consists only of a single smooth.

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

_D_e_t_a_i_l_s:

     Produces default plot showing the smooth components of a fitted
     GAM, and optionally parametric terms as well, when these can be
     handled by 'termplot'.

     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. 

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

     Fine control of plots for parametric terms can be obtained by
     calling 'termplot' directly, taking care to use its 'terms'
     argument.

_V_a_l_u_e:

     The function simply generates plots.

_W_A_R_N_I_N_G:

     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!

_A_u_t_h_o_r(_s):

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

     Henric Nilsson henric.nilsson@statisticon.se donated the code for
     the 'shade' option.

     The design is inspired by the S function of the same name
     described in Chambers and Hastie (1993) (but is not a clone).

_R_e_f_e_r_e_n_c_e_s:

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

     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

     Wood, S.N. (2004) Stable and efficient multiple smoothing
     parameter estimation for generalized additive models. J. Amer.
     Statist. Ass. 99:637-686

     <URL: http://www.maths.bath.ac.uk/~sw283/>

_S_e_e _A_l_s_o:

     'gam', 'predict.gam', 'vis.gam'

_E_x_a_m_p_l_e_s:

     library(mgcv)
     set.seed(0)
     ## fake some data...

     f1 <- function(x) {exp(2 * x)}
     f2 <- function(x) { 
       0.2*x^11*(10*(1-x))^6+10*(10*x)^3*(1-x)^10 
     }
     f3 <- function(x) {x*0}

     n<-200
     sig2<-4
     x0 <- rep(1:4,50)
     x1 <- runif(n, 0, 1)
     x2 <- runif(n, 0, 1)
     x3 <- runif(n, 0, 1)
     e <- rnorm(n, 0, sqrt(sig2))
     y <- 2*x0 + f1(x1) + f2(x2) + f3(x3) + e
     x0 <- factor(x0)

     ## fit and plot...
     b<-gam(y~x0+s(x1)+s(x2)+s(x3))
     plot(b,pages=1,residuals=TRUE,all.terms=TRUE,shade=TRUE,shade.col=2)

     ## just parametric term alone...
     termplot(b,terms="x0",se=TRUE)

     ## more use of color...
     op <- par(mfrow=c(2,2),bg="blue")
     x <- 0:1000/1000
     for (i in 1:3) {
       plot(b,select=i,rug=FALSE,col="green",
         col.axis="white",col.lab="white",all.terms=TRUE)
       for (j in 1:2) axis(j,col="white",labels=FALSE)
       box(col="white")
       eval(parse(text=paste("fx <- f",i,"(x)",sep="")))
       fx <- fx-mean(fx)
       lines(x,fx,col=2) ## overlay `truth' in red
     }
     par(op)

     ## example with 2-d plots...
     b1<-gam(y~x0+s(x1,x2)+s(x3))
     op<-par(mfrow=c(2,2))
     plot(b1,all.terms=TRUE)
     par(op) 

