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 or `"tp"'
          for a thin plate regression spline. Only thin plate
          regression splines can be used for multidimensional smooths,
          so this argument only has an effect for univariate smooths.
          Note that the `"cr"' basis is faster than the `"tp"' basis,
          particularly on large data sets.

       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.

_D_e_t_a_i_l_s:

     The function does not evaluate the variable arguments. It will
     correctly interpret calls like `s(x,14|f)' (results in pure
     regression spline smooth of one variable with a 14 knot cubic
     regression spline basis), `s(x,z,20)' (a penalized regression
     spline of 2 covariates using a 20 dimensional t.p.r.s. basis),
     etc. but this feature is purely for back compatibility reasons,
     and may not be maintained indefinitely.

_V_a_l_u_e:

     A list with 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.

 bs.type: The type of basis. 0 is cubic regression spline. 1 is thin
          plate regression spline. 0 can only be used for 1-d smooths.

   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.

_A_u_t_h_o_r(_s):

     Simon N. Wood snw@st-and.ac.uk

_S_e_e _A_l_s_o:

     `gam'

_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 - 1.396
     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)

