Creates a "spatial.neighbor" Object for a Grid

DESCRIPTION:

Creates an object of class spatial.neighbor for spatial data arranged in a rectangular lattice, or grid, allowing several definitions of a neighbor pair.

USAGE:

neighbor.grid(nrow, ncol, neighbor.type="first.order", 
              weight.fun=NULL, matrix.fun=NULL, max.horiz.dist=1, 
              max.vert.dist=1, use.pattern=F) 

REQUIRED ARGUMENTS:

nrow
integer denoting the number of rows in the spatial grid.
ncol
integer denoting the number of columns in the spatial grid.

OPTIONAL ARGUMENTS:

neighbor.type
a character string describing the type of relationship used to define the cells to be a spatial neighbor pair. Partial matching is allowed. Valid values are:

"none" - if a null neighbor matrix is to be generated (no neighbors).

"first.order" - a neighbor matrix with pattern:

.ta 1i 1.3i 1.6i 0 1 0 1 X 1 0 1 0



for interior point X, where regions in the lattice denoted by "1" are neighbors of the region "X" and all other regions are not considered neighbors.

"second.order" - a neighbor matrix with pattern:

1 1 1 1 X 1 1 1 1



for interior point X, where regions in the lattice denoted by "1" are neighbors of the region "X", and all other regions are not considered neighbors.

"diagonal" - a neighbor matrix with pattern:

1 0 1 0 X 0 1 0 1



for interior point X, where regions in the lattice denoted by "1" are neighbors of the region "X", and all other regions are not considered neighbors.

"hexagonal.in" - a neighbor matrix with pattern:

0 1 1 1 X 1 0 1 1



for interior point X, where regions in the lattice denoted by "1" are neighbors of the region "X", and all other regions are not considered neighbors. This pattern may be used with hexagonal grids in which the top row is indented.

"hexagonal.out" - a neighbor matrix with pattern:

1 1 0 1 X 1 1 1 0



for interior point X, where regions in the lattice denoted by "1" are neighbors of the region "X", and all other regions are not considered neighbors. This pattern may be used with hexagonal grids in which the top row is not indented.

"user" - the user specifies the neighbors (or the neighbor pattern, see argument use.pattern) using the function arguments weight.fun and matrix.fun.
weight.fun
a function with calling sequence:

weight.fun(row1, col1, row2, col2)

which accepts the row and column numbers for two regions (row1, col1), and (row2, col2) in the grid and computes a neighbor weight for the two cells. The function should return a single double precision value. If the weight is zero, the regions are not "neighbors". To reduce the computations, the max.horiz.dist and max.vert.dist arguments can be used to reduce the number of regions examined to determine if they are neighbors.
matrix.fun
a function with calling sequence

matrix.fun(row1, col1, row2, col2)

used to compute the type of the neighbor relationship for the two regions (row1, col1) and (row2, col2). The value return should be a single integer value. Consider a region in which north-south neighbors qualitatively different from east-west neighbors, because, say, of a north-south mountain range. In this and other similar cases, it might make sense to specify different parameterizations for different neighbor relationships. If a small number of different kinds of neighbor relationships can be defined, the matrix.fun routine can be used to specify these types. When a positive neighbor weight is found, function matrix.fun is called. Its return value specifies the type of the neighbor relationship.
max.horiz.dist
the maximum horizontal distance on either side of the current grid region to look for neighbors. This argument is used in conjunction with matrix.fun or weight.fun when searching for neighbors. When defining the cells to search, max.horiz.dist=1 indicates to search the adjoining "columns" of the grid (as well as the current column), max.horiz.dist=2 says to search the adjoining two columns, etc.
max.vert.dist
the maximum vertical distance on either side of the current grid region to look for neighbors. This argument is used in conjunction with matrix.fun or weight.fun when searching for neighbors. When defining the regions to search, max.vert.dist=1 indicates to search the adjoining rows of the grid (as well as the current row), max.vert.dist=2 says to search the adjoining two rows, etc.
use.pattern
a logical value, if TRUE, weight.fun and matrix.fun, if present, are called only for a rectangular subset of the grid, where the subset is the minimum subset needed as specified by arguments max.vert.dist and max.horiz.dist. This small subset is used to set a pattern of weights (and neighbor types), and this pattern is used to generate the "spatial.neighbor" object. Notice that when use.pattern is TRUE, weight.fun and matrix.fun are only called for the cells in a max.vert.dist x max.horiz.dist subset of the grid, saving considerable computational time.

VALUE:

an object of class "spatial.neighbor". In the "spatial.neighbor" object, regions are labeled consecutively, with the regions down the first column of the grid coming first, the elements down the second column coming next, and so on. For example, in a 5 by 3 grid the region labels are:



.ta 1i 1.3i 1.6i 1 6 11 2 7 12 3 8 13 4 9 14 5 10 15

DETAILS:

Objects of class "spatial.neighbor" contain spatial weights defining the strength of associations between observations. These objects are required by routines slm, spatial.cor, and other spatial modeling functions. Methods for efficiently defining these objects on regular and irregular grids are essential.

Function neighbor.grid can be used to generate " spatial.neighbor" objects on regular grids. Consider a 30 by 30 spatial grid. This grid contains 900 regions and 900 x 899 = 809,100 possible spatial neighbors. For any one region, the number of spatial neighbors is likely to be quite small, usually less than 10, but there are 899 possible spatial neighbors for this region. The arguments max.vert.dist and max.horiz.dist can be used to limit the search for spatial neighbors to regions "closest" to the region being considered. Further savings in cpu time are possible. It is possible, by setting use.pattern=TRUE, to generate an entire neighbor object specifying neighbors for all regions on a grid using a "pattern" of neighbor weights provided by a representative region of the grid, where the pattern weights can be defined by the S-PLUS function weight.fun . Once an initial pattern has been defined, this pattern of weights is replicated over the entire region in an obvious way, significantly reducing the computational time. On a 30 by 30 grid and using the default values for max.vert.dist and max.horiz.dist, only 8*900 calls to weight.fun need be made (as compared to 899*900 calls otherwise). If use.pattern=TRUE, only eight calls (3 * 3 - 1) are made.

SEE ALSO:

, .

EXAMPLES:

my.grid <- neighbor.grid(nrow=10, ncol=20, neighbor.type="first") 
the.weights  <- function(row1, col1, row2, col2) 
{ 
        if(abs(row1 - row2)) 
                return(1/(abs(col2 - col1) + 1)) 
        else return(0) 
} 
two.types <- function(row1, col1, row2, col2) { 
        if (col1 < col2) return(1) 
        else return (2) 
} 
zz <- neighbor.grid(10, 20, neighbor.type="user", weight.fun=the.weights, 
        matrix.fun=two.types, use.pattern=T)