spatial.neighbor(neighbor.matrix, nregion=dim(neighbor.matrix)[1])
spatial.neighbor(row.id, col.id, weights=rep(1, length(row.id)),
                 nregion=max(c(row.id,col.id)), symmetric=F,
                 matrix.id=<<see below>>)

neighbor.matrix:

a matrix of neighbor weights (where all weights are often 1) from which the object of class "spatial.neighbor" is to be constructed. This must be a square matrix such that if element [i,j] is non-zero, then spatial regions i and j are considered neighbors, and its value is used as a weight in measures of correlation or in further model-fitting. This is also known as the contiguity matrix.

row.id:

integer vector. The row indices of the non-zero elements of the neighbor weight matrix. The i-th element of row.id and the i-th element of col.id specify two regions which are spatial neighbors. Two regions are spatial neighbors if observations from the two regions have a non-zero spatial weight and vice-versa. This is ignored if neighbor.matrix is given.

col.id:

integer vector (of the same length as row.id) with the column indices of the non-zero elements of the neighbor weight matrix. This is ignored if neighbor.matrix is given.

It is important to note that even if a pair of regions c(row.id[i],col.id[i]) are spatial neighbors, the permuted pair c(col.id[i],row.id[i]) does not have to define spatial neighbors (corresponding contiguity matrix element can be zero). For example, consider two regions on a river, and suppose that a region corresponding to row.id[i] is downstream from the region in col.id[i] and neighbors. By this definition, "downstream of" the transpose pairing need not satisfy a neighbor relationship. See argument symmetric below.

weights:

numeric vector of the same length as row.id and col.id. weights[i] gives a weight for the corresponding neighbor pair relationship, given in c(row.id[i],col.id[i]). If weights is not specified (and argument neighbor.matrix is not used), then the spatial weights are all set equal to 1. Each spatial weight defines the strength of the association between two neighbors. This argument is ignored if neighbor.matrix is given as each of the matrix elements are then considered to be neighbor weights.

nregion:

integer stating the total number of regions or spatial units. If not given, this value is computed from the number of unique elements in row.id and col.id as the maximum of all the regions given therein max(c(row.id,col.id)).

symmetric:

logical flag: should the neighbor matrix be considered symmetric?. If TRUE, the spatial weights matrix is computed by assuming that if the i-th neighbor pair c(row.id[i],col.id[i]) has neighbor weight given by w=weights[i] then so does the matrix element c(col.id[i],row.id[i]). Only half of the weights need be specified in this case. If TRUE, routine spatial.condense is called to remove redundant values. When neighbor.matrix is given, its symmetry is determined within the function, otherwise, it defaults to FALSE.

matrix.id:

integer vector of length equal to the total number of spatial neighbors. This can be used to differentiate various types of neighbors. For example, spatial regression models may differentiate between north-south neighbors as compared to east-west neighbors. The values of vector matrix.id should then indicate the neighbor types. If missing, a single neighbor type is assumed (with one neighbor matrix).

Another method for constructing an object of class "spatial.neighbor" is by directly specifying the row and column numbers (and the weight value) of the non-zero elements of the contiguity matrix which is usually a sparse matrix. A sparse representation is usually preferred in practice. In this case, row.id[i] gives the row of the i-th non-negative element of the neighbor matrix, and the corresponding element col.id[i] gives its column index. Thus, each pair c(row.id[i],col.id[i]) represents a pair of neighboring spatial units. The strength of their association can then be given by weights[i].

Notice that row.id and col.id contain INDICES of the contiguity matrix and NOT the region identifiers which could be character strings or some such. These are used to expand the full contiguity matrix, so we should have representation for all indices 1 through nregion, though it is possible to have islands in between. Use the function check.islands to check for these islands, and remap their indexing if that is desirable.

It is possible to specify two or more types of neighbor relationships. For example, the user may want to model a spatial relationship depending upon the angle of the line connecting neighbor centers i.e. considering directional relationships. For this example, let Type-1 neighbors be north-south neighbors, and let Type-2 neighbors be east-west neighbors; neighbors along a diagonal could be modeled with weights proportional to .707 (the sine of 45 degrees), for instance.

Consider the elements of row.id, col.id, and weights corresponding to a distinct value, k, of the vector matrix.id. The spatial neighbor matrix can be expressed as a matrix A[k] such that A[k][row.id,col.id]=weights, and all other elements are zero. Consider a parameter vector rho of length g, many spatial covariance matrices used in spatial regression models can be expressed as a weighted linear combination of the contiguity matrices A[k], rho[k]*A[k], for values of k varying in 1:g.

row.index <- c(1,1,2,2,3)
col.index <- c(2,3,1,3,4)
# Assume we have no information about the strength of the spatial
# association.  All weights are 1.
neighbour <- spatial.neighbor(row.id=row.index, col.id=col.index)