```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)

```