*! version 1.0.0 15mar2010
help spmat tobanded

Title

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

Syntax

spmat tobanded objname1 [objname2]
[, options]

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