\HeaderA{formula.gam}{GAM formula}{formula.gam}
\keyword{models}{formula.gam}
\keyword{smooth}{formula.gam}
\keyword{regression}{formula.gam}
\begin{Description}\relax
Description of \code{\LinkA{gam}{gam}} formula (see Details), and how to extract it from a fitted \code{gam} object.
\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'gam':
formula(x,...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] fitted model objects of class \code{gam} (see \code{\LinkA{gamObject}{gamObject}}) as produced by \code{gam()}.
\item[\code{...}] un-used in this case
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The formula supplied to \code{\LinkA{gam}{gam}} is exactly like that supplied to 
\code{\LinkA{glm}{glm}} except that soooth terms, \code{\LinkA{s}{s}} and \code{\LinkA{te}{te}} can
be added to the right hand side (and \code{.} is not supported in \code{gam} formulae).

Smooth terms are specified by expressions of the form: \\
\code{s(x1,x2,...,k=12,fx=FALSE,bs="tp",by=z,id=1)}\\
where \code{x1}, \code{x2}, etc. are the covariates which the smooth
is a function of, and \code{k} is the dimension of the basis used to
represent the smooth term. If \code{k} is not
specified then basis specific defaults are used.  
\code{fx} is used to indicate whether or not this term should be unpenalized, 
and therefore have a fixed number of degrees of freedom set by \code{k} 
(almost always \code{k-1}). \code{bs} indicates the basis to use for the smooth:
the built in options are described in \code{\LinkA{smooth.terms}{smooth.terms}}, and user defined 
smooths can be added (see \code{\LinkA{user.defined.smooth}{user.defined.smooth}}). If \code{bs} is not supplied 
then the default \code{"tp"} (\code{\LinkA{tprs}{tprs}}) basis is used. 
\code{by} can be used to specify a variable by which
the smooth should be multiplied. For example \code{gam(y\textasciitilde{}s(x,by=z))}
would specify a model \eqn{ E(y) = f(x)z}{E(y)=f(x)z} where
\eqn{f(\cdot)}{f(.)} is a smooth function. The \code{by} 
option is particularly useful for models in
which different functions of the same variable are required for
each level of a factor and for `varying coefficient models': see \code{\LinkA{gam.models}{gam.models}}. 
\code{id} is used to give smooths identities: smooths with the same identity have
the same basis, penalty and smoothing parameter (but different coefficients, so they are 
different functions). 

An alternative for specifying smooths of more than one covariate is e.g.: \\
\code{te(x,z,bs=c("tp","tp"),m=c(2,3),k=c(5,10))}\\ which would specify a tensor product 
smooth of the two covariates \code{x} and \code{z} constructed from marginal t.p.r.s. bases 
of dimension 5 and 10 with marginal penalties of order 2 and 3. Any combination of basis types is 
possible, as is any number of covariates. \code{\LinkA{te}{te}} provides further information. 

Both \code{s} and \code{te} terms accept an \code{sp} argument of supplied smoothing parameters: positive 
values are taken  as fixed values to be used, negative to indicate that the parameter should be estimated. If
\code{sp} is supplied then it over-rides whatever is in the \code{sp} argument to \code{gam}, if it is not supplied 
then it defaults to all negative, but does not over-ride the \code{sp} argument to \code{gam}.

Formulae can involve nested or ``overlapping'' terms such as \\
\code{y\textasciitilde{}s(x)+s(z)+s(x,z)} or \code{y\textasciitilde{}s(x,z)+s(z,v)}:\\ see
\code{\LinkA{gam.side}{gam.side}} for further details and examples. 

Smooth terms in a \code{gam} formula will accept matrix arguments as covariates (and corresponding \code{by} variable), 
in which case a `summation convention' is invoked. Consider the example of \code{s(X,Z,by=L)} where \code{X}, \code{Z}
and \code{L} are n by m matrices. Let \code{F} be the n by m matrix that results from evaluating the smooth at the values in 
\code{X} and \code{Z}. Then the contribution to the linear predictor from the term will be
\code{rowSums(F*L)} (note the element-wise multiplication). This convention allows the linear predictor of the GAM
to depend on (a discrete approximation to) any linear functional of a smooth: see \code{\LinkA{linear.functional.terms}{linear.functional.terms}} for more information and examples (including functional linear models/signal regression).

Note that \code{gam} allows any term in the model formula to be penalized (possibly by multiple penalties), 
via the \code{paraPen} argument. See 
\code{\LinkA{gam.models}{gam.models}} for details and example code.
\end{Details}
\begin{Value}
Returns the model formula, \code{x\$formula}. Provided so that \code{anova} methods
print an appropriate description of the model.
\end{Value}
\begin{Author}\relax
Simon N. Wood \email{simon.wood@r-project.org}
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{gam}{gam}}
\end{SeeAlso}

