te.html | searchcode

/RdotNET/bin/lib/R/library/mgcv/html/te.html

http://rdotnet.googlecode.com/
HTML | 254 lines | 221 code | 33 blank | 0 comment | 0 complexity | d324c6d0b3bc90d404081bad74989d48 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.1, LGPL-2.0, BSD-3-Clause, AGPL-3.0

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html><head><title>R: Define tensor product smooths in GAM formulae</title>

<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">

<link rel="stylesheet" type="text/css" href="../../R.css">

</head><body>



<table width="100%" summary="page for te {mgcv}"><tr><td>te {mgcv}</td><td align="right">R Documentation</td></tr></table>

<h2>Define tensor product smooths in GAM formulae</h2>





<h3>Description</h3>



<p>

Function used in definition of tensor product smooth terms within

<code>gam</code> model formulae. The function does not evaluate a

smooth - it exists purely to help set up a model using tensor product 

based smooths.

</p>





<h3>Usage</h3>



<pre>te(..., k=NA,bs="cr",m=0,d=NA,by=NA,fx=FALSE,mp=TRUE,np=TRUE)

</pre>





<h3>Arguments</h3>



<table summary="R argblock">

<tr valign="top"><td><code>...</code></td>

<td>

a list of variables that are the covariates that this

smooth is a function of.</td></tr>

<tr valign="top"><td><code>k</code></td>

<td>

the dimension(s) of the bases used to represent the smooth term.

If not supplied then set to <code>5^d</code>. If supplied as a single number then this 

basis dimension is used for each basis. If supplied as an array then the elements are

the dimensions of the component (marginal) bases of the tensor

product. See <code><a href="choose.k.html">choose.k</a></code> for further information.</td></tr>

<tr valign="top"><td><code>bs</code></td>

<td>

array (or single character string) specifying the type for each 

marginal basis. <code>"cr"</code> for cubic regression spline; <code>"cs"</code> for cubic

regression spline with shrinkage; <code>"cc"</code> for periodic/cyclic 

cubic regression spline; <code>"tp"</code> for thin plate regression spline;

<code>"ts"</code> for t.p.r.s. with extra shrinkage. User defined bases can 

also be used here (see <code><a href="smooth.construct.html">smooth.construct</a></code> for an example). If only one 

identifier is given then this is used for all bases.</td></tr>

<tr valign="top"><td><code>m</code></td>

<td>

The order of the penalty for each t.p.r.s. term (e.g. 2 for

normal cubic spline penalty with 2nd derivatives). If a single number is given 

then it is used for all terms. <code>0</code> autoinitializes. <code>m</code> is ignored for the 

<code>"cr"</code> and <code>"cc"</code> bases.</td></tr>

<tr valign="top"><td><code>d</code></td>

<td>

array of marginal basis dimensions. For example if you want a smooth for 3 covariates 

made up of a tensor product of a 2 dimensional t.p.r.s. basis and a 1-dimensional basis, then 

set <code>d=c(2,1)</code>.</td></tr>

<tr valign="top"><td><code>by</code></td>

<td>

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 <code>by</code>

variable would usually be the dummy variable coding one level of the

factor. See the examples below.</td></tr>

<tr valign="top"><td><code>fx</code></td>

<td>

indicates whether the term is a fixed d.f. regression

spline (<code>TRUE</code>) or a penalized regression spline (<code>FALSE</code>).</td></tr>

<tr valign="top"><td><code>mp</code></td>

<td>

<code>TRUE</code> to use multiple penalties for the smooth. <code>FALSE</code> to use only 

a single penalty: single penalties are not recommended - they tend to allow only rather 

wiggly models.</td></tr>

<tr valign="top"><td><code>np</code></td>

<td>

<code>TRUE</code> to use the `normal parameterization' for a tensor

product smooth. This parameterization represents any 1-d marginal smooths

using a parameterization where the parameters are function values at `knots'

spread evenly through the data. The parameterization makes the penalties

easily interpretable, however it can reduce numerical stability.</td></tr>

</table>



<h3>Details</h3>



<p>

Smooths of several covariates can be constructed from tensor products of the bases

used to represent smooths of one (or sometimes more) of the covariates. To do this `marginal' bases

are produced with associated model matrices and penalty matrices, and these are then combined in the

manner described in <code><a href="tensor.prod.model.matrix.html">tensor.prod.model.matrix</a></code> and <code><a href="tensor.prod.model.matrix.html">tensor.prod.penalties</a></code>, to produce 

a single model matrix for the smooth, but multiple penalties (one for each marginal basis). The basis dimension 

of the whole smooth is the product of the basis dimensions of the marginal smooths.

</p>

<p>

An option for operating with a single penalty (The Kronecker product of the marginal penalties) is provided, but 

it is rarely of practical use: the penalty is typically so rank deficient that even the smoothest resulting model 

will have rather high estimated degrees of freedom. 

</p>

<p>

Tensor product smooths are especially useful for representing functions of covariates measured in different units, 

although they are typically not quite as nicely behaved as t.p.r.s. smooths for well scaled covariates.

</p>

<p>

Note also that GAMs constructed from lower rank tensor product smooths are

nested within GAMs constructed from higher rank tensor product smooths if the

same marginal bases are used in both cases (the marginal smooths themselves

are just special cases of tensor product smooths.)

</p>

<p>

The `normal parameterization' (<code>np=TRUE</code>) re-parameterizes the marginal

smooths of a tensor product smooth so that the parameters are function values

at a set of points spread evenly through the range of values of the covariate

of the smooth. This means that the penalty of the tensor product associated

with any particular covariate direction can be interpreted as the penalty of

the appropriate marginal smooth applied in that direction and averaged over

the smooth. Currently this is only done for marginals of a single

variable. This parameterization can reduce numerical stability for when used

with marginal smooths other than <code>"cc"</code>, <code>"cr"</code> and <code>"cs"</code>: if

this causes problems, set <code>np=FALSE</code>.

</p>

<p>

The function does not evaluate the variable arguments.

</p>





<h3>Value</h3>



<p>

A class <code>tensor.smooth.spec</code> object defining a tensor product smooth

to be turned into a basis and penalties by the <code>smooth.construct.tensor.smooth.spec</code> function. 

<br>

The returned object contains the following items:

</p>

<table summary="R argblock">

<tr valign="top"><td><code>margin</code></td>

<td>

A list of <code>smooth.spec</code> objects of the type returned by <code><a href="s.html">s</a></code>, 

defining the basis from which the tensor product smooth is constructed.</td></tr>

<tr valign="top"><td><code>term</code></td>

<td>

An array of text strings giving the names of the covariates that 

the term is a function of.</td></tr>

<tr valign="top"><td><code>by</code></td>

<td>

is the name of any <code>by</code> variable as text (<code>"NA"</code> for none).</td></tr>

<tr valign="top"><td><code>fx</code></td>

<td>

logical array with element for each penalty of the term

(tensor product smooths have multiple penalties). <code>TRUE</code> if the penalty is to 

be ignored, <code>FALSE</code>, otherwise. </td></tr>

<tr valign="top"><td><code>full.call</code></td>

<td>

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 <code>s()</code> with all the

options spelled out explicitly.</td></tr>

<tr valign="top"><td><code>label</code></td>

<td>

A suitable text label for this smooth term.</td></tr>

<tr valign="top"><td><code>dim</code></td>

<td>

The dimension of the smoother - i.e. the number of

covariates that it is a function of.</td></tr>

<tr valign="top"><td><code>mp</code></td>

<td>

<code>TRUE</code> is multiple penalties are to be used (default).</td></tr>

<tr valign="top"><td><code>np</code></td>

<td>

<code>TRUE</code> to re-parameterize 1-D marginal smooths in terms of function

values (defualt).</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. (2006) Low rank scale invariant tensor product smooths for

Generalized Additive Mixed Models. Biometrics

</p>

<p>

<a href="http://www.maths.bath.ac.uk/~sw283/">http://www.maths.bath.ac.uk/~sw283/</a>

</p>





<h3>See Also</h3>



<p>

<code><a href="s.html">s</a></code>,<code><a href="gam.html">gam</a></code>,<code><a href="gamm.html">gamm</a></code>

</p>





<h3>Examples</h3>



<pre>



# following shows how tensor pruduct deals nicely with 

# badly scaled covariates (range of x 5% of range of z )

test1&lt;-function(x,z,sx=0.3,sz=0.4)  

{ x&lt;-x*20

  (pi**sx*sz)*(1.2*exp(-(x-0.2)^2/sx^2-(z-0.3)^2/sz^2)+

  0.8*exp(-(x-0.7)^2/sx^2-(z-0.8)^2/sz^2))

}

n&lt;-500

old.par&lt;-par(mfrow=c(2,2))

x&lt;-runif(n)/20;z&lt;-runif(n);

xs&lt;-seq(0,1,length=30)/20;zs&lt;-seq(0,1,length=30)

pr&lt;-data.frame(x=rep(xs,30),z=rep(zs,rep(30,30)))

truth&lt;-matrix(test1(pr$x,pr$z),30,30)

f &lt;- test1(x,z)

y &lt;- f + rnorm(n)*0.2

b1&lt;-gam(y~s(x,z))

persp(xs,zs,truth);title("truth")

vis.gam(b1);title("t.p.r.s")

b2&lt;-gam(y~te(x,z))

vis.gam(b2);title("tensor product")

b3&lt;-gam(y~te(x,z,bs=c("tp","tp")))

vis.gam(b3);title("tensor product")

par(old.par)



test2&lt;-function(u,v,w,sv=0.3,sw=0.4)  

{ ((pi**sv*sw)*(1.2*exp(-(v-0.2)^2/sv^2-(w-0.3)^2/sw^2)+

  0.8*exp(-(v-0.7)^2/sv^2-(w-0.8)^2/sw^2)))*(u-0.5)^2*20

}

n &lt;- 500

v &lt;- runif(n);w&lt;-runif(n);u&lt;-runif(n)

f &lt;- test2(u,v,w)

y &lt;- f + rnorm(n)*0.2

# tensor product of a 2-d thin plate regression spline and 1-d cr spline

b &lt;- gam(y~te(v,w,u,k=c(30,5),d=c(2,1),bs=c("tp","cr")))

op &lt;- par(mfrow=c(2,2))

vis.gam(b,cond=list(u=0),color="heat",zlim=c(-0.2,3.5))

vis.gam(b,cond=list(u=.33),color="heat",zlim=c(-0.2,3.5))

vis.gam(b,cond=list(u=.67),color="heat",zlim=c(-0.2,3.5))

vis.gam(b,cond=list(u=1),color="heat",zlim=c(-0.2,3.5))

par(op)



</pre>







<hr><div align="center">[Package <em>mgcv</em> version 1.3-19 <a href="00Index.html">Index]</a></div>



</body></html>