s {mgcv} | R Documentation

## Defining smooths in GAM formulae

### Description

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.

### Usage

    s(..., k=-1,fx=FALSE,bs="tp",m=0,by=NA)

### Arguments

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

### Details

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.

### Value

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.

### Author(s)

Simon N. Wood simon@stats.gla.ac.uk

### See Also

`gam`

### Examples

    # 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)

[Package Contents]