poly2nb: Construct neighbours list from polygon list

In spdep: Spatial Dependence: Weighting Schemes, Statistics and Models

Description

The function builds a neighbours list based on regions with contiguous boundaries, that is sharing one or more boundary point. The current function is in part interpreted and may run slowly for many regions or detailed boundaries, but from 0.2-16 should not fail because of lack of memory when single polygons are built of very many border coordinates.

Usage

poly2nb(pl, row.names = NULL, snap=sqrt(.Machine$double.eps),
 queen=TRUE, useC=TRUE, foundInBox=NULL)

Arguments

pl	list of polygons of class extending SpatialPolygons
row.names	character vector of region ids to be added to the neighbours list as attribute region.id, default seq(1, nrow(x)); if polys has a region.id attribute, it is copied to the neighbours list.
snap	boundary points less than snap distance apart are considered to indicate contiguity
queen	if TRUE, a single shared boundary point meets the contiguity condition, if FALSE, more than one shared point is required; note that more than one shared boundary point does not necessarily mean a shared boundary line
useC	default TRUE, doing the work loop in C, may be set to false to revert to R code calling two C functions in an n*k work loop, where k is the average number of candidate neighbours
foundInBox	default NULL using R code, possibly parallelised if a snow cluster is available, otherwise a list of length (n-1) with integer vectors of candidate neighbours (j > i), or NULL if all candidates were (j < i) (as created by the poly_findInBoxGEOS function in rgeos for clean polygons)

Value

A neighbours list with class nb. See card for details of “nb” objects.

Note

From 0.5-8, the function includes faster bounding box indexing and other improvements contributed by Micah Altman. If a cluster is provided using set.ClusterOption, it will be used for finding candidate bounding box overlaps for exact testing for contiguity.

Author(s)

Roger Bivand [e-mail] with contributions from Micah Altman

See Also

summary.nb, card

Examples

example(columbus)
coords <- coordinates(columbus)
xx <- poly2nb(columbus)
dxx <- diffnb(xx, col.gal.nb)
plot(columbus, border="grey")
plot(col.gal.nb, coords, add=TRUE)
plot(dxx, coords, add=TRUE, col="red")
title(main=paste("Differences (red) in Columbus GAL weights (black)",
 "and polygon generated queen weights", sep="\n"))
xxx <- poly2nb(columbus, queen=FALSE)
dxxx <- diffnb(xxx, col.gal.nb)
plot(columbus, border = "grey")
plot(col.gal.nb, coords, add = TRUE)
plot(dxxx, coords, add = TRUE, col = "red")
title(main=paste("Differences (red) in Columbus GAL weights (black)",
 "and polygon generated rook weights", sep="\n"))
cards <- card(xx)
maxconts <- which(cards == max(cards))
if(length(maxconts) > 1) maxconts <- maxconts[1]
fg <- rep("grey", length(cards))
fg[maxconts] <- "red"
fg[xx[[maxconts]]] <- "green"
plot(columbus, col=fg)
title(main="Region with largest number of contiguities")
example(nc.sids)
system.time(xxnb <- poly2nb(nc.sids))
plot(nc.sids)
plot(xxnb, coordinates(nc.sids), add=TRUE, col="blue")

Example output

Loading required package: sp
Loading required package: Matrix

colmbs> require(maptools)
Loading required package: maptools
Checking rgeos availability: TRUE

colmbs> columbus <- readShapePoly(system.file("etc/shapes/columbus.shp",
colmbs+  package="spdep")[1])

colmbs> col.gal.nb <- read.gal(system.file("etc/weights/columbus.gal",
colmbs+  package="spdep")[1])
Warning message:
use rgdal::readOGR or sf::st_read 
Warning message:
In diffnb(xx, col.gal.nb) : region.id differ; using ids of first list
Warning message:
In diffnb(xxx, col.gal.nb) : region.id differ; using ids of first list

nc.sds> require(maptools)

nc.sds> nc.sids <- readShapePoly(system.file("etc/shapes/sids.shp", package="spdep")[1],
nc.sds+   ID="FIPSNO", proj4string=CRS("+proj=longlat +ellps=clrk66"))
NOTE: rgdal::checkCRSArgs: no proj_defs.dat in PROJ.4 shared files

nc.sds> rn <- sapply(slot(nc.sids, "polygons"), function(x) slot(x, "ID"))

nc.sds> ncCC89_nb <- read.gal(system.file("etc/weights/ncCC89.gal", package="spdep")[1],
nc.sds+   region.id=rn)

nc.sds> ncCR85_nb <- read.gal(system.file("etc/weights/ncCR85.gal", package="spdep")[1],
nc.sds+   region.id=rn)

nc.sds> ## Not run: 
nc.sds> ##D plot(nc.sids, border="grey")
nc.sds> ##D plot(ncCR85_nb, coordinates(nc.sids), add=TRUE, col="blue")
nc.sds> ##D plot(nc.sids, border="grey")
nc.sds> ##D plot(ncCC89_nb, coordinates(nc.sids), add=TRUE, col="blue")
nc.sds> ## End(Not run)
nc.sds> 
nc.sds> 
nc.sds> 
Warning message:
use rgdal::readOGR or sf::st_read 
   user  system elapsed 
  0.017   0.000   0.017 

spdep documentation built on Aug. 19, 2017, 3:01 a.m.