smooth2random {mgcv}  R Documentation 
Convert a smooth to a form suitable for estimating as random effect
Description
A generic function for converting mgcv
smooth objects to forms suitable for estimation as random effects by e.g. lme
. Exported mostly for use by other package developers.
Usage
smooth2random(object,vnames,type=1)
Arguments
object 
an 
vnames 
a vector of names to avoid as dummy variable names in the random effects form. 
type 

Details
There is a duality between smooths and random effects which means that smooths can be estimated using mixed modelling software. This function converts standard mgcv
smooth objects to forms suitable for estimation by lme
, for example. A service routine for gamm
exported for use by package developers. See examples for creating prediction matrices for new data, corresponding to the random and fixed effect matrices returned when type=2
.
Value
A list.
rand 
a list of random effects, including grouping factors, and
a fixed effects matrix. Grouping factors, model matrix and model
matrix name attached as attributes, to each element. Alternatively, for 
trans.D 
A vector, trans.D, that transforms coefs, in order [rand1, rand2,... fix] back to original parameterization. If null, then taken as vector of ones. 
trans.U 
A matrix, trans.U, that transforms coefs, in order [rand1, rand2,... fix] back to original parameterization. If null, then not needed. If null then taken as identity. 
Xf 
A matrix for the fixed effects, if any. 
fixed 

rind 
an index vector such that if br is the vector of random coefficients for the term, br[rind] is the coefs in order for this term. 
pen.ind 
index of which penalty penalizes each coefficient: 0 for unpenalized. 
Author(s)
Simon N. Wood simon.wood@rproject.org.
References
Wood S.N. (2017) Generalized Additive Models: An Introduction with R (2nd edition). Chapman and Hall/CRC Press.
See Also
Examples
## Simple type 1 'lme' style...
library(mgcv)
x < runif(30)
sm < smoothCon(s(x),data.frame(x=x))[[1]]
smooth2random(sm,"")
## Now type 2 'lme4' style...
z < runif(30)
dat < data.frame(x=x,z=z)
sm < smoothCon(t2(x,z),dat)[[1]]
re < smooth2random(sm,"",2)
str(re)
## For prediction after fitting we might transform parameters back to
## original parameterization using 'rind', 'trans.D' and 'trans.U',
## and call PredictMat(sm,newdata) to get the prediction matrix to
## multiply these transformed parameters by.
## Alternatively we could obtain fixed and random effect Prediction
## matrices corresponding to the results from smooth2random, which
## can be used with the fit parameters without transforming them.
## The following shows how...
s2rPred < function(sm,re,data) {
## Function to aid prediction from smooths represented as type==2
## random effects. re must be the result of smooth2random(sm,...,type=2).
X < PredictMat(sm,data) ## get prediction matrix for new data
## transform to r.e. parameterization
if (!is.null(re$trans.U)) X < X%*%re$trans.U
X < t(t(X)*re$trans.D)
## reorder columns according to random effect reordering...
X[,re$rind] < X[,re$pen.ind!=0]
## reorder penalization index in same way
pen.ind < re$pen.ind; pen.ind[re$rind] < pen.ind[pen.ind>0]
## start return object...
r < list(rand=list(),Xf=X[,which(re$pen.ind==0),drop=FALSE])
for (i in 1:length(re$rand)) { ## loop over random effect matrices
r$rand[[i]] < X[,which(pen.ind==i),drop=FALSE]
attr(r$rand[[i]],"s.label") < attr(re$rand[[i]],"s.label")
}
names(r$rand) < names(re$rand)
r
} ## s2rPred
## use function to obtain prediction random and fixed effect matrices
## for first 10 elements of 'dat'. Then confirm that these match the
## first 10 rows of the original model matrices, as they should...
r < s2rPred(sm,re,dat[1:10,])
range(r$Xfre$Xf[1:10,])
range(r$rand[[1]]re$rand[[1]][1:10,])