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)