\HeaderA{vis.gam}{Visualization of GAM objects}{vis.gam}
\aliasA{persp.gam}{vis.gam}{persp.gam}
\keyword{hplot}{vis.gam}
\keyword{models}{vis.gam}
\keyword{smooth}{vis.gam}
\keyword{regression}{vis.gam}
\begin{Description}\relax
Produces perspective or contour plot views of \code{gam} model
predictions, fixing all but the values in \code{view} to the  values supplied in \code{cond}.
\end{Description}
\begin{Usage}
\begin{verbatim}
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,...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a \code{gam} object, produced by \code{gam()}
\item[\code{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
\code{names(x\$model)}. i.e. \code{terms} are used, rather than \code{variables}.

\item[\code{cond}] a named list of the values to use for the other predictor terms
(not in \code{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 \code{names(x\$model)}.

\item[\code{n.grid}] The number of grid nodes in each direction used for calculating the 
plotted surface.
\item[\code{too.far}] plot grid nodes that are too far from the points defined by the variables given in \code{view} 
can be excluded from the plot. \code{too.far} determines what is too far. The grid is scaled into the unit 
square along with the \code{view} variables and then grid nodes more than \code{too.far} from the predictor variables 
are excluded.
\item[\code{col}] The colours for the facets of the plot. If this is \code{NA} then if \code{se}>0 the facets are transparent, 
otherwise the colour scheme specified in \code{color} is used. If \code{col} is not \code{NA} then it is used as the facet 
colour.
\item[\code{color}] the colour scheme to use for plots when \code{se}<=0. One of \code{"topo"}, \code{"heat"}, \code{"cm"}, 
\code{"terrain"}, \code{"gray"} or \code{"bw"}. Schemes \code{"gray"} and
\code{"bw"} also modify the colors used when \code{se}>0.
\item[\code{contour.col}] sets the colour of contours when using \code{plot.type="contour"}. Default scheme used if \code{NULL}.
\item[\code{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 \code{se} standard errors, one at the predicted values and one at
the predicted values plus \code{se} standard errors.
\item[\code{type}] \code{"link"} to plot on linear predictor scale and \code{"response"} to plot on the response scale.
\item[\code{plot.type}] one of \code{"contour"} or \code{"persp"}.
\item[\code{zlim}] a two item array giving the lower and upper limits for the z-axis
scale. \code{NULL} to choose automatically.
\item[\code{nCol}] The number of colors to use in color schemes.
\item[\code{...}] other options to pass on to \code{\LinkA{persp}{persp}},
\code{\LinkA{image}{image}} or \code{\LinkA{contour}{contour}}. In particular \code{ticktype="detailed"} will add proper axes 
labelling to the plots. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The x and y limits are determined by the ranges of the terms named in \code{view}. If \code{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 +/- \code{se} standard errors. Parts of the x-y plane too far from
data can be excluded by setting \code{too.far}

All options to the underlying graphics functions can be reset by passing them
as extra arguments \code{...}: such supplied values will always over-ride the
default values used by \code{vis.gam}.
\end{Details}
\begin{Value}
Simply produces a plot.
\end{Value}
\begin{Author}\relax
Simon Wood \email{simon.wood@r-project.org}

Based on an original idea and design by Mike Lonergan.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{persp}{persp}} and \code{\LinkA{gam}{gam}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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

\end{ExampleCode}
\end{Examples}

