help spmat tobanded


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


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.


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.


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.


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.


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


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,

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

Also see

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