s                    package:mgcv                    R Documentation

_D_e_f_i_n_i_n_g _s_m_o_o_t_h_s _i_n _G_A_M _f_o_r_m_u_l_a_e

_D_e_s_c_r_i_p_t_i_o_n:

     Function used in definition of smooth terms within 'gam' model
     formulae. The function does not evaluate a (spline) smooth - it
     exists purely to help set up a model using spline based smooths.

_U_s_a_g_e:

     s(..., k=-1,fx=FALSE,bs="tp",m=NA,by=NA,xt=NULL,id=NULL,sp=NULL)

_A_r_g_u_m_e_n_t_s:

     ...: a list of variables that are the covariates that this smooth
          is a function of.

       k: the dimension of the basis used to represent the smooth term.
          The default depends on the number of variables that the
          smooth is a function of. 'k' should not be less than the
          dimension of the null space of the penalty for the term (see
          'null.space.dimension'), but will be reset if it is. See
          'choose.k' for further information.

      fx: indicates whether the term is a fixed d.f. regression spline
          ('TRUE') or a penalized regression spline ('FALSE').

      bs: a two letter character string indicating the (penalized)
          smoothing basis to use. (eg '"tp"' for thin plate regression
          spline, '"cr"' for cubic regression spline). see
          'smooth.terms' for an over view of what is available. 

       m: The order of the penalty for this term (e.g. 2 for normal
          cubic spline penalty with 2nd derivatives when using  default
          t.p.r.s basis). 'NA' signals autoinitialization. Only some
          smooth classes use this. The '"ps"'  class can use a 2 item
          array giving the basis and penalty order separately.

      by: a numeric or factor variable of the same dimension as each
          covariate.  In the numeric vector case the elements multiply
          the smooth evaluated at the corresponding  covariate values
          (a `varying coefficient model' results).  In the factor case
          causes a replicate of the smooth to be produced for each
          factor level. See 'gam.models' for further details. May also
          be a matrix  if covariates are matrices: in this case
          implements linear functional of a smooth  (see 'gam.models'
          and 'linear.functional.terms' for details). 

      xt: Any extra information required to set up a particular basis.
          Used e.g. to set large data set handling behaviour for '"tp"'
          basis.

      id: A label or integer identifying this term in order to link its
          smoothing parameters to others of the same type. If two or
          more terms have the same  'id' then they will have the same
          smoothing paramsters, and, by default, the same bases (first
          occurance defines basis type, but data from all terms  used
          in basis construction). An 'id' with a factor 'by' variable
          causes the smooths at each factor level to have the same
          smoothing parameter.

      sp: any supplied smoothing parameters for this term. Must be an
          array of the same length as the number of penalties for this
          smooth. Positive or zero elements are taken as fixed 
          smoothing parameters. Negative elements signal
          auto-initialization. Over-rides values supplied in  'sp'
          argument to 'gam'. Ignored by 'gamm'.

_D_e_t_a_i_l_s:

     The function does not evaluate the variable arguments. To use this
     function to specify use of your own smooths, note the
     relationships between the inputs and the output object and see the
     example in 'smooth.construct'.

_V_a_l_u_e:

     A class 'xx.smooth.spec' object, where 'xx' is a basis identifying
     code given by the 'bs' argument of 's'. These 'smooth.spec'
     objects define smooths and are turned into bases and penalties by
     'smooth.construct' method functions. 

     The returned object contains the following items:

    term: An array of text strings giving the names of the covariates
          that  the term is a function of.

  bs.dim: The dimension of the basis used to represent the smooth.

   fixed: TRUE if the term is to be treated as a pure regression spline
          (with fixed degrees of freedom); FALSE if it is to be treated
          as a penalized regression spline

     dim: The dimension of the smoother - i.e. the number of covariates
          that it is a function of.

 p.order: The order of the t.p.r.s. penalty, or 0 for auto-selection of
          the penalty order.

      by: is the name of any 'by' variable as text ('"NA"' for none).

   label: A suitable text label for this smooth term.

      xt: The object passed in as argument 'xt'.

      id: An identifying label or number for the smooth, linking it to
          other smooths. Defaults to 'NULL' for no linkage. 

      sp: array of smoothing parameters for the term (negative for
          auto-estimation). Defaults to 'NULL'.

_A_u_t_h_o_r(_s):

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

_R_e_f_e_r_e_n_c_e_s:

     Wood, S.N. (2003) Thin plate regression splines. J.R.Statist.Soc.B
     65(1):95-114

     Wood S.N. (2006) Generalized Additive Models: An Introduction with
     R. Chapman and Hall/CRC Press.

     <URL: http://www.maths.bath.ac.uk/~sw283/>

_S_e_e _A_l_s_o:

     'te', 'gam', 'gamm'

_E_x_a_m_p_l_e_s:

     # example utilising `by' variables
     library(mgcv)
     set.seed(0)
     n<-200;sig2<-4
     x1 <- runif(n, 0, 1);x2 <- runif(n, 0, 1);x3 <- runif(n, 0, 1)
     fac<-c(rep(1,n/2),rep(2,n/2)) # create factor
     fac.1<-rep(0,n)+(fac==1);fac.2<-1-fac.1 # and dummy variables
     fac<-as.factor(fac)
     f1 <-  exp(2 * x1) - 3.75887
     f2 <-  0.2 * x1^11 * (10 * (1 - x1))^6 + 10 * (10 * x1)^3 * (1 - x1)^10
     f<-f1*fac.1+f2*fac.2+x2
     e <- rnorm(n, 0, sqrt(abs(sig2)))
     y <- f + e
     # NOTE: smooths will be centered, so need to include fac in model....
     b<-gam(y~fac+s(x1,by=fac)+x2) 
     plot(b,pages=1)