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=0,by=NA)

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

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

      bs: this can be '"cr"' for a cubic regression spline, '"cs"' for
          a cubic regression spline with shrinkage, '"cc"' for a cyclic
          (periodic) spline, '"tp"' for a thin plate regression spline,
          '"ts"' for a thin plate regression spline with shrinkage or a
          user defined  character string for other user defined smooth
          classes. Of the built in alternatives, only thin plate
          regression splines can be used for multidimensional smooths.
          Note that the '"cr"' and '"cc"' bases are faster to set up
          than the '"tp"' basis, particularly on large data sets
          (although the 'knots' argument to 'gam' can be used to get
          round this).

       m: The order of the penalty for this t.p.r.s. term (e.g. 2 for
          normal cubic spline penalty with 2nd derivatives). O signals
          autoinitialization, which sets the order to the lowest value
          satisfying 2m>d+1, where d is the number of covariates: this
          choise ensures visual smoothness. In addition, m must satisfy
          the technical restriction 2m>d, otherwise it will be
          autoinitialized.

      by: specifies a covariate by which the whole smooth term is to be
          multiplied. This is particularly useful for creating models
          in which a smooth interacts with a factor: in this case the
          'by' variable would usually be the dummy variable coding one
          level of the factor. See the examples below. This is the
          means by which `variable coefficient models' can be
          specified.

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

full.call: Text for pasting into a string to be converted to a gam
          formula, which has the values of function options given
          explicitly - this is useful for constructing a fully expanded
          gam formula which can be used without needing access to any
          variables that may have been used to define 'k', 'fx', 'bs'
          or 'm' in the original call. i.e. this is text which when
          parsed and evaluated generates a call to 's()' with all the
          options spelled out explicitly.

   label: A suitable text label for this smooth term.

_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. (2000)  Modelling and Smoothing Parameter Estimation
     with Multiple  Quadratic Penalties. J.R.Statist.Soc.B
     62(2):413-428

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

     <URL: http://www.stats.gla.ac.uk/~simon/>

_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.1)+s(x1,by=fac.2)+x2) 
     plot(b,pages=1)