formula.gam               package:mgcv               R Documentation

GAM formula

Description:

     Description of 'gam' formula (see Details), and how to extract it
     from a fitted 'gam' object.

Usage:

     ## S3 method for class 'gam':
     formula(x,...)

Arguments:

       x: fitted model objects of class 'gam' (see 'gamObject') as
          produced by 'gam()'.

     ...: un-used in this case

Details:

     The formula supplied to 'gam' is exactly like that supplied to 
     'glm' except that soooth terms, 's' and 'te' can be added to the
     right hand side (and '.' is not supported in 'gam' formulae).

     Smooth terms are specified by expressions of the form: 
      's(x1,x2,...,k=12,fx=FALSE,bs="tp",by=z,id=1)'
      where 'x1', 'x2', etc. are the covariates which the smooth is a
     function of, and 'k' is the dimension of the basis used to
     represent the smooth term. If 'k' is not specified then basis
     specific defaults are used.   '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 'k'  (almost always 'k-1').
     'bs' indicates the basis to use for the smooth: the built in
     options are described in 'smooth.terms', and user defined  smooths
     can be added (see 'user.defined.smooth'). If 'bs' is not supplied 
     then the default '"tp"' ('tprs') basis is used.  'by' can be used
     to specify a variable by which the smooth should be multiplied.
     For example 'gam(y~s(x,by=z))' would specify a model E(y)=f(x)z
     where f(.) is a smooth function. The '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 'gam.models'.  '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.: 
      '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 'x' and '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. 'te' provides further information. 

     Both 's' and 'te' terms accept an '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 'sp' is supplied then it over-rides whatever is in
     the 'sp' argument to 'gam', if it is not supplied  then it
     defaults to all negative, but does not over-ride the 'sp' argument
     to 'gam'.

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

     Smooth terms in a 'gam' formula will accept matrix arguments as
     covariates (and corresponding 'by' variable),  in which case a
     `summation convention' is invoked. Consider the example of
     's(X,Z,by=L)' where 'X', 'Z' and 'L' are n by m matrices. Let 'F'
     be the n by m matrix that results from evaluating the smooth at
     the values in  'X' and 'Z'. Then the contribution to the linear
     predictor from the term will be '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 'linear.functional.terms'
     for more information and examples (including functional linear
     models/signal regression).

     Note that 'gam' allows any term in the model formula to be
     penalized (possibly by multiple penalties),  via the 'paraPen'
     argument. See  'gam.models' for details and example code.

Value:

     Returns the model formula, 'x$formula'. Provided so that 'anova'
     methods print an appropriate description of the model.

Author(s):

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

See Also:

     'gam'

