EVOLUTION-MANAGER
Edit File: smooth.construct.tp.smooth.spec.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Penalized thin plate regression splines in GAMs</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for smooth.construct.tp.smooth.spec {mgcv}"><tr><td>smooth.construct.tp.smooth.spec {mgcv}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Penalized thin plate regression splines in GAMs</h2> <h3>Description</h3> <p><code><a href="gam.html">gam</a></code> can use isotropic smooths of any number of variables, specified via terms like <code>s(x,z,bs="tp",m=3)</code> (or just <code>s(x,z)</code> as this is the default basis). These terms are based on thin plate regression splines. <code>m</code> specifies the order of the derivatives in the thin plate spline penalty. </p> <p>If <code>m</code> is a vector of length 2 and the second element is zero, then the penalty null space of the smooth is not included in the smooth: this is useful if you need to test whether a smooth could be replaced by a linear term, or construct models with odd nesting structures. </p> <p>Thin plate regression splines are constructed by starting with the basis and penalty for a full thin plate spline and then truncating this basis in an optimal manner, to obtain a low rank smoother. Details are given in Wood (2003). One key advantage of the approach is that it avoids the knot placement problems of conventional regression spline modelling, but it also has the advantage that smooths of lower rank are nested within smooths of higher rank, so that it is legitimate to use conventional hypothesis testing methods to compare models based on pure regression splines. Note that the basis truncation does not change the meaning of the thin plate spline penalty (it penalizes exactly what it would have penalized for a full thin plate spline). </p> <p>The t.p.r.s. basis and penalties can become expensive to calculate for large datasets. For this reason the default behaviour is to randomly subsample <code>max.knots</code> unique data locations if there are more than <code>max.knots</code> such, and to use the sub-sample for basis construction. The sampling is always done with the same random seed to ensure repeatability (does not reset R RNG). <code>max.knots</code> is 2000, by default. Both seed and <code>max.knots</code> can be modified using the <code>xt</code> argument to <code>s</code>. Alternatively the user can supply knots from which to construct a basis. </p> <p>The <code>"ts"</code> smooths are t.p.r.s. with the penalty modified so that the term is shrunk to zero for high enough smoothing parameter, rather than being shrunk towards a function in the penalty null space (see details). </p> <h3>Usage</h3> <pre> ## S3 method for class 'tp.smooth.spec' smooth.construct(object, data, knots) ## S3 method for class 'ts.smooth.spec' smooth.construct(object, data, knots) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>object</code></td> <td> <p>a smooth specification object, usually generated by a term <code>s(...,bs="tp",...)</code> or <code>s(...,bs="ts",...)</code></p> </td></tr> <tr valign="top"><td><code>data</code></td> <td> <p>a list containing just the data (including any <code>by</code> variable) required by this term, with names corresponding to <code>object$term</code> (and <code>object$by</code>). The <code>by</code> variable is the last element.</p> </td></tr> <tr valign="top"><td><code>knots</code></td> <td> <p>a list containing any knots supplied for basis setup — in same order and with same names as <code>data</code>. Can be <code>NULL</code></p> </td></tr> </table> <h3>Details</h3> <p> The default basis dimension for this class is <code>k=M+k.def</code> where <code>M</code> is the null space dimension (dimension of unpenalized function space) and <code>k.def</code> is 8 for dimension 1, 27 for dimension 2 and 100 for higher dimensions. This is essentially arbitrary, and should be checked, but as with all penalized regression smoothers, results are statistically insensitive to the exact choise, provided it is not so small that it forces oversmoothing (the smoother's degrees of freedom are controlled primarily by its smoothing parameter). </p> <p>The default is to set <code>m</code> (the order of derivative in the thin plate spline penalty) to the smallest value satisfying <code>2m > d+1</code> where <code>d</code> if the number of covariates of the term: this yields ‘visually smooth’ functions. In any case <code>2m>d</code> must be satisfied. </p> <p>The constructor is not normally called directly, but is rather used internally by <code><a href="gam.html">gam</a></code>. To use for basis setup it is recommended to use <code><a href="smooth.construct.html">smooth.construct2</a></code>. </p> <p>For these classes the specification <code>object</code> will contain information on how to handle large datasets in their <code>xt</code> field. The default is to randomly subsample 2000 ‘knots’ from which to produce a tprs basis, if the number of unique predictor variable combinations in excess of 2000. The default can be modified via the <code>xt</code> argument to <code><a href="s.html">s</a></code>. This is supplied as a list with elements <code>max.knots</code> and <code>seed</code> containing a number to use in place of 2000, and the random number seed to use (either can be missing). </p> <p>For these bases <code>knots</code> has two uses. Firstly, as mentioned already, for large datasets the calculation of the <code>tp</code> basis can be time-consuming. The user can retain most of the advantages of the t.p.r.s. approach by supplying a reduced set of covariate values from which to obtain the basis - typically the number of covariate values used will be substantially smaller than the number of data, and substantially larger than the basis dimension, <code>k</code>. This approach is the one taken automatically if the number of unique covariate values (combinations) exceeds <code>max.knots</code>. The second possibility is to avoid the eigen-decomposition used to find the t.p.r.s. basis altogether and simply use the basis implied by the chosen knots: this will happen if the number of knots supplied matches the basis dimension, <code>k</code>. For a given basis dimension the second option is faster, but gives poorer results (and the user must be quite careful in choosing knot locations). </p> <p>The shrinkage version of the smooth, eigen-decomposes the wiggliness penalty matrix, and sets its zero eigenvalues to small multiples of the smallest strictly positive eigenvalue. The penalty is then set to the matrix with eigenvectors corresponding to those of the original penalty, but eigenvalues set to the peturbed versions. This penalty matrix has full rank and shrinks the curve to zero at high enough smoothing parameters. </p> <h3>Value</h3> <p> An object of class <code>"tprs.smooth"</code> or <code>"ts.smooth"</code>. In addition to the usual elements of a smooth class documented under <code><a href="smooth.construct.html">smooth.construct</a></code>, this object will contain: </p> <table summary="R valueblock"> <tr valign="top"><td><code>shift</code></td> <td> <p>A record of the shift applied to each covariate in order to center it around zero and avoid any co-linearity problems that might otehrwise occur in the penalty null space basis of the term. </p> </td></tr> <tr valign="top"><td><code>Xu</code></td> <td> <p>A matrix of the unique covariate combinations for this smooth (the basis is constructed by first stripping out duplicate locations).</p> </td></tr> <tr valign="top"><td><code>UZ</code></td> <td> <p>The matrix mapping the t.p.r.s. parameters back to the parameters of a full thin plate spline.</p> </td></tr> <tr valign="top"><td><code>null.space.dimension</code></td> <td> <p>The dimension of the space of functions that have zero wiggliness according to the wiggliness penalty for this term.</p> </td></tr> </table> <h3>Author(s)</h3> <p> Simon N. Wood <a href="mailto:simon.wood@r-project.org">simon.wood@r-project.org</a></p> <h3>References</h3> <p>Wood, S.N. (2003) Thin plate regression splines. J.R.Statist.Soc.B 65(1):95-114 </p> <h3>Examples</h3> <pre> require(mgcv); n <- 100; set.seed(2) x <- runif(n); y <- x + x^2*.2 + rnorm(n) *.1 ## is smooth significantly different from straight line? summary(gam(y~s(x,m=c(2,0))+x,method="REML")) ## not quite ## is smooth significatly different from zero? summary(gam(y~s(x),method="REML")) ## yes! ## Fool bam(...,discrete=TRUE) into (strange) nested ## model fit... set.seed(2) ## simulate some data... dat <- gamSim(1,n=400,dist="normal",scale=2) dat$x1a <- dat$x1 ## copy x1 so bam allows 2 copies of x1 ## Following removes identifiability problem, by removing ## linear terms from second smooth, and then re-inserting ## the one that was not a duplicate (x2)... b <- bam(y~s(x0,x1)+s(x1a,x2,m=c(2,0))+x2,data=dat,discrete=TRUE) ## example of knot based tprs... k <- 10; m <- 2 y <- y[order(x)];x <- x[order(x)] b <- gam(y~s(x,k=k,m=m),method="REML", knots=list(x=seq(0,1,length=k))) X <- model.matrix(b) par(mfrow=c(1,2)) plot(x,X[,1],ylim=range(X),type="l") for (i in 2:ncol(X)) lines(x,X[,i],col=i) ## compare with eigen based (default) b1 <- gam(y~s(x,k=k,m=m),method="REML") X1 <- model.matrix(b1) plot(x,X1[,1],ylim=range(X1),type="l") for (i in 2:ncol(X1)) lines(x,X1[,i],col=i) ## see ?gam </pre> <hr /><div style="text-align: center;">[Package <em>mgcv</em> version 1.8-28 <a href="00Index.html">Index</a>]</div> </body></html>