EVOLUTION-MANAGER
Edit File: smooth.construct.bs.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 B-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.bs.smooth.spec {mgcv}"><tr><td>smooth.construct.bs.smooth.spec {mgcv}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Penalized B-splines in GAMs</h2> <h3>Description</h3> <p><code><a href="gam.html">gam</a></code> can use smoothing splines based on univariate B-spline bases with derivative based penalties, specified via terms like <code>s(x,bs="bs",m=c(3,2))</code>. <code>m[1]</code> controls the spline order, with <code>m[1]=3</code> being a cubic spline, <code>m[1]=2</code> being quadratic, and so on. The integrated square of the <code>m[2]</code>th derivative is used as the penalty. So <code>m=c(3,2)</code> is a conventional cubic spline. Any further elements of <code>m</code>, after the first 2, define the order of derivative in further penalties. If <code>m</code> is supplied as a single number, then it is taken to be <code>m[1]</code> and <code>m[2]=m[1]-1</code>, which is only a conventional smoothing spline in the <code>m=3</code>, cubic spline case. Notice that the definition of the spline order in terms of <code>m[1]</code> is intuitive, but differs to that used with the <code><a href="smooth.construct.tp.smooth.spec.html">tprs</a></code> and <code><a href="smooth.construct.ps.smooth.spec.html">p.spline</a></code> bases. See details for options for controlling the interval over which the penalty is evaluated (which can matter if it is necessary to extrapolate). </p> <h3>Usage</h3> <pre> ## S3 method for class 'bs.smooth.spec' smooth.construct(object, data, knots) ## S3 method for class 'Bspline.smooth' Predict.matrix(object, data) </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(x,bs="bs",...)</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>. See details for further information.</p> </td></tr> </table> <h3>Details</h3> <p> The basis and penalty are sparse (although sparse matrices are not used to represent them). <code>m[2]>m[1]</code> will generate an error, since in that case the penalty would be based on an undefined derivative of the basis, which makes no sense. The terms can have multiple penalties of different orders, for example <code>s(x,bs="bs",m=c(3,2,1,0))</code> specifies a cubic basis with 3 penalties: a conventional cubic spline penalty, an integrated square of first derivative penalty, and an integrated square of function value penalty. </p> <p>The default basis dimension, <code>k</code>, is the larger of 10 and <code>m[1]</code>. <code>m[1]</code> is the lower limit on basis dimension. If knots are supplied, then the number of supplied knots should be <code>k + m[1] + 1</code>, and the range of the middle <code>k-m[1]+1</code> knots should include all the covariate values. Alternatively, 2 knots can be supplied, denoting the lower and upper limits between which the spline can be evaluated (making this range too wide mean that there is no information about some basis coefficients, because the corresponding basis functions have a span that includes no data). Unlike P-splines, splines with derivative based penalties can have uneven knot spacing, without a problem. </p> <p>Another option is to supply 4 knots. Then the outer 2 define the interval over which the penalty is to be evaluated, while the inner 2 define an interval within which all but the outermost 2 knots should lie. Normally the outer 2 knots would be the interval over which predictions might be required, while the inner 2 knots define the interval within which the data lie. This option allows the penalty to apply over a wider interval than the data, while still placing most of the basis functions where the data are. This is useful in situations in which it is necessary to extrapolate slightly with a smooth. Only applying the penalty over the interval containing the data amounts to a model in which the function could be less smooth outside the interval than within it, and leads to very wide extrapolation confidence intervals. However the alternative of evaluating the penalty over the whole real line amounts to asserting certainty that the function has some derivative zeroed away from the data, which is equally unreasonable. It is prefereable to build a model in which the same smoothness assumtions apply over both data and extrapolation intervals, but not over the whole real line. See example code for practical illustration. </p> <p>Linear extrapolation is used for prediction that requires extrapolation (i.e. prediction outside the range of the interior <code>k-m[1]+1</code> knots — the interval over which the penalty is evaluated). Such extrapolation is not allowed in basis construction, but is when predicting. </p> <p>It is possible to set a <code>deriv</code> flag in a smooth specification or smooth object, so that a model or prediction matrix produces the requested derivative of the spline, rather than evaluating it. </p> <h3>Value</h3> <p> An object of class <code>"Bspline.smooth"</code>. See <code><a href="smooth.construct.html">smooth.construct</a></code>, for the elements that this object will contain. </p> <h3>WARNING</h3> <p><code>m[1]</code> directly controls the spline order here, which is intuitively sensible, but different to other bases.</p> <h3>Author(s)</h3> <p> Simon N. Wood <a href="mailto:simon.wood@r-project.org">simon.wood@r-project.org</a>. Extrapolation ideas joint with David Miller.</p> <h3>References</h3> <p>Wood, S.N. (2017) P-splines with derivative based penalties and tensor product smoothing of unevenly distributed data. Statistics and Computing. 27(4) 985-989 <a href="http://arxiv.org/abs/1605.02446">http://arxiv.org/abs/1605.02446</a> </p> <h3>See Also</h3> <p><code><a href="smooth.construct.ps.smooth.spec.html">p.spline</a></code></p> <h3>Examples</h3> <pre> require(mgcv) set.seed(5) dat <- gamSim(1,n=400,dist="normal",scale=2) bs <- "bs" ## note the double penalty on the s(x2) term... b <- gam(y~s(x0,bs=bs,m=c(4,2))+s(x1,bs=bs)+s(x2,k=15,bs=bs,m=c(4,3,0))+ s(x3,bs=bs,m=c(1,0)),data=dat,method="REML") plot(b,pages=1) ## Extrapolation example, illustrating the importance of considering ## the penalty carefully if extrapolating... f3 <- function(x) 0.2 * x^11 * (10 * (1 - x))^6 + 10 * (10 * x)^3 * (1 - x)^10 ## test function n <- 100;x <- runif(n) y <- f3(x) + rnorm(n)*2 ## first a model with first order penalty over whole real line (red) b0 <- gam(y~s(x,m=1,k=20),method="ML") ## now a model with first order penalty evaluated over (-.5,1.5) (black) op <- options(warn=-1) b <- gam(y~s(x,bs="bs",m=c(3,1),k=20),knots=list(x=c(-.5,0,1,1.5)), method="ML") options(op) ## and the equivalent with same penalty over data range only (blue) b1 <- gam(y~s(x,bs="bs",m=c(3,1),k=20),method="ML") pd <- data.frame(x=seq(-.7,1.7,length=200)) fv <- predict(b,pd,se=TRUE) ul <- fv$fit + fv$se.fit*2; ll <- fv$fit - fv$se.fit*2 plot(x,y,xlim=c(-.7,1.7),ylim=range(c(y,ll,ul)),main= "Order 1 penalties: red tps; blue bs on (0,1); black bs on (-.5,1.5)") ## penalty defined on (-.5,1.5) gives plausible predictions and intervals ## over this range... lines(pd$x,fv$fit);lines(pd$x,ul,lty=2);lines(pd$x,ll,lty=2) fv <- predict(b0,pd,se=TRUE) ul <- fv$fit + fv$se.fit*2; ll <- fv$fit - fv$se.fit*2 ## penalty defined on whole real line gives constant width intervals away ## from data, as slope there must be zero, to avoid infinite penalty: lines(pd$x,fv$fit,col=2) lines(pd$x,ul,lty=2,col=2);lines(pd$x,ll,lty=2,col=2) fv <- predict(b1,pd,se=TRUE) ul <- fv$fit + fv$se.fit*2; ll <- fv$fit - fv$se.fit*2 ## penalty defined only over the data interval (0,1) gives wild and wide ## extrapolation since penalty has been `turned off' outside data range: lines(pd$x,fv$fit,col=4) lines(pd$x,ul,lty=2,col=4);lines(pd$x,ll,lty=2,col=4) ## construct smooth of x. Model matrix sm$X and penalty ## matrix sm$S[[1]] will have many zero entries... x <- seq(0,1,length=100) sm <- smoothCon(s(x,bs="bs"),data.frame(x))[[1]] ## another example checking penalty numerically... m <- c(4,2); k <- 15; b <- runif(k) sm <- smoothCon(s(x,bs="bs",m=m,k=k),data.frame(x), scale.penalty=FALSE)[[1]] sm$deriv <- m[2] h0 <- 1e-3; xk <- sm$knots[(m[1]+1):(k+1)] Xp <- PredictMat(sm,data.frame(x=seq(xk[1]+h0/2,max(xk)-h0/2,h0))) sum((Xp%*%b)^2*h0) ## numerical approximation to penalty b%*%sm$S[[1]]%*%b ## `exact' version ## ...repeated with uneven knot spacing... m <- c(4,2); k <- 15; b <- runif(k) ## produce the required 20 unevenly spaced knots... knots <- data.frame(x=c(-.4,-.3,-.2,-.1,-.001,.05,.15, .21,.3,.32,.4,.6,.65,.75,.9,1.001,1.1,1.2,1.3,1.4)) sm <- smoothCon(s(x,bs="bs",m=m,k=k),data.frame(x), knots=knots,scale.penalty=FALSE)[[1]] sm$deriv <- m[2] h0 <- 1e-3; xk <- sm$knots[(m[1]+1):(k+1)] Xp <- PredictMat(sm,data.frame(x=seq(xk[1]+h0/2,max(xk)-h0/2,h0))) sum((Xp%*%b)^2*h0) ## numerical approximation to penalty b%*%sm$S[[1]]%*%b ## `exact' version </pre> <hr /><div style="text-align: center;">[Package <em>mgcv</em> version 1.8-28 <a href="00Index.html">Index</a>]</div> </body></html>