smoothCon {mgcv} | R Documentation

## Prediction/Construction wrapper functions for GAM smooth terms

### Description

Wrapper functions for construction of and prediction from smooth terms in a GAM. The purpose of the wrappers is to allow user-transparant re-parameterization of smooth terms, in order to allow identifiability constraints to be absorbed into the parameterization of each term, if required. The routine also handles ‘by’ variables and construction of identifiability constraints automatically, although this behaviour can be over-ridden.

### Usage

    smoothCon(object,data,knots=NULL,absorb.cons=FALSE,
              scale.penalty=TRUE,n=nrow(data),dataX=NULL,
              null.space.penalty=FALSE,sparse.cons=0,
              diagonal.penalty=FALSE,apply.by=TRUE)
    PredictMat(object,data,n=nrow(data))

### Arguments

`object` | is a smooth specification object or a smooth object.
`data` | A data frame, model frame or list containing the values of the (named) covariates at which the smooth term is to be evaluated. If it's a list then `n` must be supplied.
`knots` | An optional data frame supplying any knot locations to be supplied for basis construction.
`absorb.cons` | Set to `TRUE` in order to have identifiability constraints absorbed into the basis.
`scale.penalty` | should the penalty coefficient matrix be scaled to have approximately the same ‘size’ as the inner product of the terms model matrix with itself? This can improve the performance of `gamm` fitting.
`n` | number of values for each covariate, or if a covariate is a matrix, the number of rows in that matrix: must be supplied explicitly if `data` is a list.
`dataX` | Sometimes the basis should be set up using data in `data`, but the model matrix should be constructed with another set of data provided in `dataX` — `n` is assumed to be the same for both. Facilitates smooth id's.
`null.space.penalty` | Should an extra penalty be added to the smooth which will penalize the components of the smooth in the penalty null space: provides a way of penalizing terms out of the model altogether.
`apply.by` | set to `FALSE` to have basis setup exactly as in default case, but to return add an additional matrix `X0` to the return object, containing the model matrix without the `by` variable, if a `by` variable is present. Useful for `bam` discrete method setup.
`sparse.cons` | If `0` then default sum to zero constraints are used. If `-1` then sweep and drop sum to zero constraints are used (default with `bam`). If `1` then one coefficient is set to zero as constraint for sparse smooths. If `2` then sparse coefficient sum to zero constraints are used for sparse smooths. None of these options has an effect if the smooth supplies its own constraint.
`diagonal.penalty` | If `TRUE` then the smooth is reparameterized to turn the penalty into an identity matrix, with the final diagonal elements zeroed (corresponding to the penalty nullspace). May result in a matrix `diagRP` in the returned object for use by `PredictMat`.

### Details

These wrapper functions exist to allow smooths specified using `smooth.construct` and `Predict.matrix` method functions to be re-parameterized so that identifiability constraints are no longer required in fitting. This is done in a user transparent manner, but is typically of no importance in use of GAMs. The routine's also handle `by` variables and will create default identifiability constraints.

If a user defined smooth constructor handles `by` variables itself, then its returned smooth object should contain an object `by.done`. If this does not exist then `smoothCon` will use the default code. Similarly if a user defined `Predict.matrix` method handles `by` variables internally then the returned matrix should have a `"by.done"` attribute.

Default centering constraints, that terms should sum to zero over the covariates, are produced unless the smooth constructor includes a matrix `C` of constraints. To have no constraints (in which case you had better have a full rank penalty!) the matrix `C` should have no rows. There is an option to use centering constraint that generate no, or limited infil, if the smoother has a sparse model matrix.

`smoothCon` returns a list of smooths because factor `by` variables result in multiple copies of a smooth, each multiplied by the dummy variable associated with one factor level. `smoothCon` modifies the smooth object labels in the presence of `by` variables, to ensure that they are unique, it also stores the level of a by variable factor associated with a smooth, for later use by `PredictMat`.

The parameterization used by `gam` can be controlled via `gam.control`.

### Value

From `smoothCon` a list of `smooth` objects returned by the appropriate `smooth.construct` method function. If constraints are to be absorbed then the objects will have attributes `"qrc"` and `"nCons"`. `"nCons"` is the number of constraints. `"qrc"` is usually the qr decomposition of the constraint matrix (returned by `qr`), but if it is a single positive integer it is the index of the coefficient to set to zero, and if it is a negative number then this indicates that the parameters are to sum to zero.

For `predictMat` a matrix which will map the parameters associated with the smooth to the vector of values of the smooth evaluated at the covariate values given in `object`.

### Author(s)

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

### References

http://www.maths.bris.ac.uk/~sw15190/

### See Also

`gam.control`, `smooth.construct`, `Predict.matrix`

### Examples

    ## example of using smoothCon and PredictMat to set up a basis
    ## to use for regression and make predictions using the result
    library(MASS) ## load for mcycle data.
    ## set up a smoother...
    sm <- smoothCon(s(times,k=10),data=mcycle,knots=NULL)[[1]]
    ## use it to fit a regression spline model...
    beta <- coef(lm(mcycle$accel~sm$X-1))
    with(mcycle,plot(times,accel)) ## plot data
    times <- seq(0,60,length=200)  ## creat prediction times
    ## Get matrix mapping beta to spline prediction at 'times'
    Xp <- PredictMat(sm,data.frame(times=times))
    lines(times,Xp%*%beta) ## add smooth to plot

    ## Same again but using a penalized regression spline of
    ## rank 30....
    sm <- smoothCon(s(times,k=30),data=mcycle,knots=NULL)[[1]]
    E <- t(mroot(sm$S[[1]])) ## square root penalty
    X <- rbind(sm$X,0.1*E) ## augmented model matrix
    y <- c(mcycle$accel,rep(0,nrow(E))) ## augmented data
    beta <- coef(lm(y~X-1)) ## fit penalized regression spline
    Xp <- PredictMat(sm,data.frame(times=times)) ## prediction matrix
    with(mcycle,plot(times,accel)) ## plot data
    lines(times,Xp%*%beta) ## overlay smooth

[Package mgcv version 1.8-12 Index]