help spmat tobanded
-------------------------------------------------------------------------------

Title

    spmat tobanded -- Store a general spatial-weighting matrix W in banded
                        form


Syntax

        spmat tobanded objname1 [objname2] [, options]

    options                       Description
    -------------------------------------------------------------------------
    * btruncate(b B)              bin truncation
    * dtruncate(l u)              diagonal truncation
    * vtruncate(#)                value truncation
      replace                     replace objname1 or objname2
    -------------------------------------------------------------------------
    * Only one of btruncate(), dtruncate(), or vtruncate() may be specified.


Description

    spmat tobanded replaces the existing objname1 or creates the new objname2
    with the spatial-weighting matrix W stored in a banded form.  By default,
    spmat tobanded assumes that W has already a banded structure and attempts
    to store W in a banded form; see Remarks below for a distinction between
    a banded structure and a banded form.

    If the matrix cannot be stored in a banded form, spmat tobanded returns
    appropriate summary statistics.


Options

    truncate() options specify one of the three available truncation
        criteria.  The values of the spatial-weighting matrix W that meet the
        truncation criterion will be changed to zero.

        btruncate(b B) partitions the value of W into B bins and truncates to
        zero entries that fall into bin b or below.

        dtruncate(l u) truncates to zero the values of W that fall l
        diagonals below and u diagonals above the main diagonal.  Neither
        value can be greater than floor((cols(W)-1)/4).

        vtruncate(#) truncates to zero the values of W that are less than or
        equal to #.

    replace allows objname1 or objname2 to be overwritten if it already
        exists.


Remarks

    Let W be the spatial-weighting matrix

            +-             -+
            | 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
    clustered around the main diagonal.  A matrix with nonzero elements in
    the diagonals close to the main diagonal and zero elements in all the
    diagonals away from the main diagonal is called a banded matrix.  Note
    that although this matrix has a banded structure, it is still stored in a
    general (n x n) form.  We can store W more efficiently in a banded form
    as

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

    The row dimension of the banded matrix is b = (# of diagonals below the
    main diagonal + main diagonal + # of diagonals above the main diagonal).
    The elements beyond the upper and lower bands are implied to be zero and
    need not be stored.

    In general, the spatial-weighting matrix for n places is an n x n matrix,
    which implies that memory requirements increase quadratically with data
    size.  For example, a spatial-weighting matrix for n = 50,000 requires
    (50000*50000*8) / 2^30 or 18.63 GB of storage space.

    As discussed in Drukker et al. (2010a, 2010b), many spatial-weighting
    matrices can be stored in a banded form b x n, b << n, if the underlying
    data have been sorted in an ascending order from a corner place for a
    given topography.

    If we construct a contiguity matrix from the sorted data, most
    neighboring observations will cluster around the main diagonal, which
    will allow us to store the matrix in a banded form without any loss of
    information.

    If we construct an inverse-distance matrix from the sorted data, places
    that are closer to us will be located closer to the main diagonal and
    more distant places will be located farther away from the main diagonal.
    In this case, an inverse-distance matrix can be banded if we assume that
    places that lie outside of a certain perimeter are to be treated as
    non-neighbors.  truncate options provide three ways to exclude "more
    distant" places from our neighborhood.

    In either case, the banded matrix will be stored in a banded form, which
    will result in substantial storage savings.  For example, if we are able
    to squeeze neighborhood information into the bands of width 500, we can
    store the 50,000 x 50,000 matrix in a 1,001 x 50,000 form, which requires
    only (1001*50000*8) / 2^30 or 0.37 GB of memory.


Example

    Setup
        . use pollute
        . sort longitude latitude
        . spmat contiguity cobj using c103xy, id(id) norm(minmax)

    Summarize the matrix contained in the spmat object cobj to see that it is
    stored as a 541 x 541 matrix
        . spmat summarize cobj, links

    Try to band the matrix
        . spmat tobanded cobj, replace

    Summarize the matrix to see that it is stored as a 147 x 541 banded
    matrix
        . spmat summarize cobj, links


References

    Drukker, D. M., H. Peng, I. R. Prucha, and R. Raciborski. 2011a.
        Creating and managing spatial-weighting matrices using the spmat
        command.  Working paper, University of Maryland, Department of
        Economics, http://econweb.umd.edu/~prucha/Papers/WP_spmat_2011.pdf.

    -----. 2011b. Banded spatial-weighting matrices.  Working paper,
        University of Maryland, Department of Economics,


Also see

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