vis.gam                 package:mgcv                 R Documentation

_V_i_s_u_a_l_i_z_a_t_i_o_n _o_f _G_A_M _o_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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,...)

_A_r_g_u_m_e_n_t_s:

       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. Note that
          variables coerced to factors in the model formula won't work
          as view variables, and 'vis.gam' can not detect that this has
          happened when setting defaults.  

    cond: a named list of the values to use for the other predictor
          terms (not in 'view'). Variables omitted from this list will
          have the closest observed value to the median  for continuous
          variables, or the most commonly occuring level for factors.
          Parametric matrix variables have  all the entries in each
          column set to the observed column entry closest to the column
          median. 

  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. 

_D_e_t_a_i_l_s:

     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'.

_V_a_l_u_e:

     Simply produces a plot.

_W_A_R_N_I_N_G_S:

     The routine can not detect that a variable has been coerced to
     factor within a model formula,  and will therefore fail if such a
     variable is used as a 'view' variable. When setting  default
     'view' variables it can not detect this situation either, which
     can cause failures if the coerced variables are the first,
     otherwise suitable, variables encountered.

_A_u_t_h_o_r(_s):

     Simon Wood simon.wood@r-project.org

     Based on an original idea and design by Mike Lonergan.

_S_e_e _A_l_s_o:

     'persp' and 'gam'.

_E_x_a_m_p_l_e_s:

     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)
     # ..... areas where there is no data are not plotted

     # 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")

     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