vis.gam                 package:mgcv                 R Documentation

Visualization of GAM objects

Description:

     Produces perspective or contour plot views of 'gam' model
     predictions, fixing all but the values in 'view' to the  values
     supplied in 'cond'.

Usage:

     vis.gam(x,view=NULL,cond=list(),n.grid=30,too.far=0,col=NA,
             color="heat",contour.col=NULL,se=-1,type="link",
             plot.type="persp",zlim=NULL,nCol=50,...)

Arguments:

       x: a 'gam' object, produced by 'gam()'

    view: an array containing the names of the two main effect terms to
          be displayed on the  x and y dimensions of the plot. If
          omitted the first two suitable terms will be used. Names must
          be names from 'names(x$model)'. i.e. 'terms' are used, rather
          than 'variables'. 

    cond: a named list of the values to use for the other predictor
          terms (not in 'view'). Terms omitted from  this list will
          have their values set to their mean for continuous variables,
          or first level for factors. Names must correspond to
          'names(x$model)'. 

  n.grid: The number of grid nodes in each direction used for
          calculating the  plotted surface.

 too.far: plot grid nodes that are too far from the points defined by
          the variables given in 'view'  can be excluded from the plot.
          'too.far' determines what is too far. The grid is scaled into
          the unit  square along with the 'view' variables and then
          grid nodes more than 'too.far' from the predictor variables 
          are excluded.

     col: The colours for the facets of the plot. If this is 'NA' then
          if 'se'>0 the facets are transparent,  otherwise the colour
          scheme specified in 'color' is used. If 'col' is not 'NA'
          then it is used as the facet  colour.

   color: the colour scheme to use for plots when 'se'<=0. One of
          '"topo"', '"heat"', '"cm"',  '"terrain"', '"gray"' or '"bw"'.
          Schemes '"gray"' and '"bw"' also modify the colors used when
          'se'>0.

contour.col: sets the colour of contours when using
          'plot.type="contour"'. Default scheme used if 'NULL'.

      se: if less than or equal to zero then only the predicted surface
          is plotted, but if greater than zero, then 3  surfaces are
          plotted, one at the predicted values minus 'se' standard
          errors, one at the predicted values and one at the predicted
          values plus 'se' standard errors.

    type: '"link"' to plot on linear predictor scale and '"response"'
          to plot on the response scale.

plot.type: one of '"contour"' or '"persp"'.

    zlim: a two item array giving the lower and upper limits for the
          z-axis scale. 'NULL' to choose automatically.

    nCol: The number of colors to use in color schemes.

     ...: other options to pass on to 'persp', 'image' or 'contour'. In
          particular 'ticktype="detailed"' will add proper axes 
          labelling to the plots. 

Details:

     The x and y limits are determined by the ranges of the terms named
     in 'view'. If 'se'<=0 then  a single (height colour coded, by
     default) surface is produced, otherwise three (by default
     see-through) meshes are produced at  mean and +/- 'se' standard
     errors. Parts of the x-y plane too far from data can be excluded
     by setting 'too.far'

     All options to the underlying graphics functions can be reset by
     passing them as extra arguments '...': such supplied values will
     always over-ride the default values used by 'vis.gam'.

Value:

     Simply produces a plot.

Author(s):

     Simon Wood simon.wood@r-project.org

     Based on an original idea and design by Mike Lonergan.

See Also:

     'persp' and '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)
     y<-x0^2+x1*x2 +runif(n,-0.3,0.3)
     g<-gam(y~s(x0,x1,x2))
     old.par<-par(mfrow=c(2,2))
     # display the prediction surface in x0, x1 ....
     vis.gam(g,ticktype="detailed",color="heat",theta=-35)  
     vis.gam(g,se=2,theta=-35) # with twice standard error surfaces
     vis.gam(g, view=c("x1","x2"),cond=list(x0=0.75)) # different view 
     vis.gam(g, view=c("x1","x2"),cond=list(x0=.75),theta=210,phi=40,
             too.far=.07)
     # contour examples....
     vis.gam(g, view=c("x1","x2"),plot.type="contour",color="heat")
     vis.gam(g, view=c("x1","x2"),plot.type="contour",color="terrain")
     vis.gam(g, view=c("x1","x2"),plot.type="contour",color="topo")
     vis.gam(g, view=c("x1","x2"),plot.type="contour",color="cm")

     # ..... areas where there is no data are not plotted
     par(old.par)

     # Examples with factor and "by" variables

     fac<-rep(1:4,20)
     x<-runif(80)
     y<-fac+2*x^2+rnorm(80)*0.1
     fac<-factor(fac)
     b<-gam(y~fac+s(x))

     vis.gam(b,theta=-35,color="heat") # factor example

     z<-rnorm(80)*0.4   
     y<-as.numeric(fac)+3*x^2*z+rnorm(80)*0.1
     b<-gam(y~fac+s(x,by=z))

     vis.gam(b,theta=-35,color="heat",cond=list(z=1)) # by variable example

     vis.gam(b,view=c("z","x"),theta= 35) # plot against by variable

