help spmat permute-------------------------------------------------------------------------------

Title

spmat permute-- Reorder the rows and columns of the spatial-weighting matrixW

Syntax

spmatpermuteobjnamevarname

Description

spmat permutereorders the rows and columns of the spatial-weighting matrixWcontained in thespmatobjectobjname.varnameis the Stata variable containing the permutation vector, where theith observation invarnamespecifies the new column index ofW; see [M-1] permutation for a detailed discussion.

spmat permuteprepares a general spatial-weighting matrix for more efficient storage; seeRemarksinspmat tobandedfor details.

RemarksWe use a simple example to illustrate how

spmat permuteworks. Given the spatial-weighting matrixW,+- -+ | 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 ofWby performing the operation

W = W[p, p]which results in

Wbeing+- -+ |

01 0 0 0 | | 101 0 0 | | 0 101 0 | | 0 0 101 | | 0 0 0 10| +- -+where we highlighted the main diagonal. Note that all the 1s are now clustered around the main diagonal. We can now use

spmat tobandedto store the permuted matrixWin a banded form.

spmat permuterequires that the permutation vector be stored in the Stata variablevarname. Assume that we now have the unpermuted matrixWstored in thespmatobjectcobj. 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

distancemeasures the distance from the centroid of place withid=100to the centroids of all the other places. We sort the data ondistanceand generate the permutation vectorp = _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

idvariable:+--------------------+ | 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 pwill reorder the rows and columns ofWin exactly the same way as the Mata code above did.

Example--------------------------------------------------------------------------- Setup

. use pollute. spmat use cobj using pollute.spmat. spmat summarize cobjCreate the permutation vector p

. gen p = _n. sort longitude latitude. gen dist = sqrt( (longitude-longitude[1])^2 +(latitude-latitude[1])^2 ). sort distPermute the matrix

. spmat permute cobj pBand 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 seeOnline:

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