*! version 1.0.1 16mar2010
help spmat permute

Title

spmat permute -- Reorder the rows and columns of the
spatial-weighting matrix W

Syntax

spmat permute objname varname

Description

spmat permute reorders the rows and columns of the spatial-weighting
matrix W contained in the spmat object objname. varname
is the Stata variable containing the permutation vector, where the ith
observation in varname specifies the new column index of W; see
[M-1] permutation for a detailed discussion.

spmat permute prepares a general spatial-weighting matrix for
more efficient storage; see Remarks in
spmat tobanded for details.

Remarks

We use a simple example to illustrate how spmat permute works.
Given the spatial-weighting matrix W,

+- -+
| 0 1 0 0 1 |
| 1 0 0 1 0 |
| 0 0 0 0 1 |
| 0 1 0 0 0 |
| 1 0 1 0 0 |
+- -+

and the permutation vector p = (3, 5, 1, 2, 4),
we can use Mata to reorder the rows and columns of W by
performing the operation

W = W[p, p]

which results in W being

+- -+
| 0 1 0 0 0 |
| 1 0 1 0 0 |
| 0 1 0 1 0 |
| 0 0 1 0 1 |
| 0 0 0 1 0 |
+- -+

where we highlighted the main diagonal. Note that all the 1s are now
clustered around the main diagonal. We can now use
spmat tobanded to store the permuted
matrix W in a banded form.

spmat permute requires that the permutation vector be stored in
the Stata variable varname. Assume that we now have the unpermuted matrix W
stored in the spmat object cobj. The matrix represents
contiguity information for the following data:

+----------------+
| id distance |
+----------------+
| 79 5.23 |
| 82 27.56 |
| 100 0 |
| 114 1.77 |
| 140 20.47 |
+----------------+

where the variable distance measures the distance from the centroid of
place with id = 100 to the centroids of all the other places. We sort
the data on distance and generate the permutation vector p = _n,
which is just a running index 1, ..., 5:

+--------------------+
| id distance p |
+--------------------+
| 100 0 1 |
| 114 1.77 2 |
| 79 5.23 3 |
| 140 20.47 4 |
| 82 27.56 5 |
+--------------------+

We obtain our permutation vector by sorting the data back to the original order
based on the id variable:

+--------------------+
| id distance p |
+--------------------+
| 79 5.23 3 |
| 82 27.56 5 |
| 100 0 1 |
| 114 1.77 2 |
| 140 20.77 4 |
+--------------------+

Now coding spmat permute cobj p will reorder the rows and columns of
W in exactly the same way as the Mata code above did.

Example

Setup

. use pollute

. spmat use cobj using pollute.spmat

. spmat summarize cobj

Create the permutation vector p

. gen p = _n

. sort longitude latitude

. gen dist = sqrt( (longitude-longitude[1])^2 + (latitude-latitude[1])^2 )

. sort dist

Permute the matrix

. spmat permute cobj p

Band the matrix if possible

. spmat summarize cobj, banded

. if `r(canband)'==1 spmat tobanded cobj, dtr(`r(lband)' `r(uband)') replace

. spmat summarize cobj

Also see

Online: spmat, spreg, spivreg,
spmap, shp2dta, mif2dta (if installed)