EVOLUTION-MANAGER
Edit File: smooth.construct.mrf.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: Markov Random Field Smooths</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.mrf.smooth.spec {mgcv}"><tr><td>smooth.construct.mrf.smooth.spec {mgcv}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Markov Random Field Smooths</h2> <h3>Description</h3> <p>For data observed over discrete spatial units, a simple Markov random field smoother is sometimes appropriate. These functions provide such a smoother class for <code>mgcv</code>. See details for how to deal with regions with missing data. </p> <h3>Usage</h3> <pre> ## S3 method for class 'mrf.smooth.spec' smooth.construct(object, data, knots) ## S3 method for class 'mrf.smooth' Predict.matrix(object, data) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>object</code></td> <td> <p>For the <code>smooth.construct</code> method a smooth specification object, usually generated by a term <code>s(x,...,bs="mrf",xt=list(polys=foo))</code>. <code>x</code> is a factor variable giving labels for geographic districts, and the <code>xt</code> argument is obligatory: see details. For the <code>Predict.Matrix</code> method an object of class <code>"mrf.smooth"</code> produced by the <code>smooth.construct</code> method.</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>If there are more geographic areas than data were observed for, then this argument is used to provide the labels for all the areas (observed and unobserved). </p> </td></tr> </table> <h3>Details</h3> <p>A Markov random field smooth over a set of discrete areas is defined using a set of area labels, and a neighbourhood structure for the areas. The covariate of the smooth is the vector of area labels corresponding to each obervation. This covariate should be a factor, or capable of being coerced to a factor. </p> <p>The neighbourhood structure is supplied in the <code>xt</code> argument to <code>s</code>. This must contain at least one of the elements <code>polys</code>, <code>nb</code> or <code>penalty</code>. </p> <dl> <dt>polys</dt><dd><p>contains the polygons defining the geographic areas. It is a list with as many elements as there are geographic areas. <code>names(polys)</code> must correspond to the levels of the argument of the smooth, in any order (i.e. it gives the area labels). <code>polys[[i]]</code> is a 2 column matrix the rows of which specify the vertices of the polygon(s) defining the boundary of the ith area. A boundary may be made up of several closed loops: these must be separated by <code>NA</code> rows. A polygon within another is treated as a hole. The first polygon in any <code>polys[[i]]</code> should not be a hole. An example of the structure is provided by <code><a href="columb.html">columb.polys</a></code> (which contains an artificial hole in its second element, for illustration). Any list elements with duplicate names are combined into a single NA separated matrix. </p> <p>Plotting of the smooth is not possible without a <code>polys</code> object. </p> <p>If <code>polys</code> is the only element of <code>xt</code> provided, then the neighbourhood structure is computed from it automatically. To count as neigbours, polygons must exactly share one of more vertices. </p> </dd> <dt>nb</dt><dd><p>is a named list defining the neighbourhood structure. <code>names(nb)</code> must correspond to the levels of the covariate of the smooth (i.e. the area labels), but can be in any order. <code>nb[[i]]</code> is a numeric vector indexing the neighbours of the ith area. All indices are relative to <code>nb</code> itself, but can be translated using <code>names(nb)</code>. See example code. As an alternative each <code>nb[[i]]</code> can be an array of the names of the neighbours, but these will be converted to the arrays of numeric indices internally. </p> <p>If no <code>penalty</code> is provided then it is computed automatically from this list. The ith row of the penalty matrix will be zero everwhere, except in the ith column, which will contain the number of neighbours of the ith geographic area, and the columns corresponding to those geographic neighbours, which will each contain -1. </p> </dd> <dt>penalty</dt><dd><p> if this is supplied, then it is used as the penalty matrix. It should be positive semi-definite. Its row and column names should correspond to the levels of the covariate.</p> </dd> </dl> <p>If no basis dimension is supplied then the constructor produces a full rank MRF, with a coefficient for each geographic area. Otherwise a low rank approximation is obtained based on truncation of the parameterization given in Wood (2017) Section 5.4.2. See Wood (2017, section 5.8.1). </p> <p>Note that smooths of this class have a built in plot method, and that the utility function <code><a href="in.out.html">in.out</a></code> can be useful for working with discrete area data. The plot method has two schemes, <code>scheme==0</code> is colour, <code>scheme==1</code> is grey scale. </p> <p>The situation in which there are areas with no data requires special handling. You should set <code>drop.unused.levels=FALSE</code> in the model fitting function, <code><a href="gam.html">gam</a></code>, <code><a href="bam.html">bam</a></code> or <code><a href="gamm.html">gamm</a></code>, having first ensured that any fixed effect factors do not contain unobserved levels. Also make sure that the basis dimension is set to ensure that the total number of coefficients is less than the number of observations. </p> <h3>Value</h3> <p> An object of class <code>"mrf.smooth"</code> or a matrix mapping the coefficients of the MRF smooth to the predictions for the areas listed in <code>data</code>. </p> <h3>Author(s)</h3> <p> Simon N. Wood <a href="mailto:simon.wood@r-project.org">simon.wood@r-project.org</a> and Thomas Kneib (Fabian Scheipl prototyped the low rank MRF idea) </p> <h3>References</h3> <p>Wood S.N. (2017) Generalized additive models: an introduction with R (2nd edition). CRC. </p> <h3>See Also</h3> <p><code><a href="in.out.html">in.out</a></code>, <code><a href="polys.plot.html">polys.plot</a></code></p> <h3>Examples</h3> <pre> library(mgcv) ## Load Columbus Ohio crime data (see ?columbus for details and credits) data(columb) ## data frame data(columb.polys) ## district shapes list xt <- list(polys=columb.polys) ## neighbourhood structure info for MRF par(mfrow=c(2,2)) ## First a full rank MRF... b <- gam(crime ~ s(district,bs="mrf",xt=xt),data=columb,method="REML") plot(b,scheme=1) ## Compare to reduced rank version... b <- gam(crime ~ s(district,bs="mrf",k=20,xt=xt),data=columb,method="REML") plot(b,scheme=1) ## An important covariate added... b <- gam(crime ~ s(district,bs="mrf",k=20,xt=xt)+s(income), data=columb,method="REML") plot(b,scheme=c(0,1)) ## plot fitted values by district par(mfrow=c(1,1)) fv <- fitted(b) names(fv) <- as.character(columb$district) polys.plot(columb.polys,fv) ## Examine an example neighbourhood list - this one auto-generated from ## 'polys' above. nb <- b$smooth[[1]]$xt$nb head(nb) names(nb) ## these have to match the factor levels of the smooth ## look at the indices of the neighbours of the first entry, ## named '0'... nb[['0']] ## by name nb[[1]] ## same by index ## ... and get the names of these neighbours from their indices... names(nb)[nb[['0']]] b1 <- gam(crime ~ s(district,bs="mrf",k=20,xt=list(nb=nb))+s(income), data=columb,method="REML") b1 ## fit unchanged plot(b1) ## but now there is no information with which to plot the mrf </pre> <hr /><div style="text-align: center;">[Package <em>mgcv</em> version 1.8-28 <a href="00Index.html">Index</a>]</div> </body></html>