help for spwmatrix

Title

spwmatrix --- Generates, imports, and exports spatial weights

Table of Contents

Click on the "Jump To" link at the top right corner.

Syntax

Import first order contiguity spatial weights from ArcGIS (SWM file) and GeoDa (GAL file) or spatial weights from a dta or
a text file

spwmatrix import using filename, wname(wght_name)
[dta text swm(idvar_name) Other_options]

Generate geographic and economic distance-based spatial weights using latitude and longitude

spwmatrix gecon varlist [if] [in], wname(wght_name) [wtype(bin|inv|econ|invecon)
cart r(#) dband(numlist) ///

alpha(#) knn(#) econvar(1) beta(#) Other_options]

Generate social network and socio-economic spatial weights

spwmatrix socio 2 [if] [in], wname(wght_name)
wtype(socnet|socecon) [idvar(3) dthres(#) gamma(#) ///

snn(#) dmins(1) Other_options]

where import, gecon, and socio are sub-commands.

Main Options

wname(wght_name) indicate the name of the spatial weights matrix to be generated

wtype(bin|inv|econ|invecon|socnet|socecon) request binary, distance decay, economic distance, inverse economic distance,
social network, or socio-economic spatial weights

dta import spatial weights from a dta file

text import spatial weights from a comma or tab delimited text file

swm(idvar_name) import spatial weights generated in ArcGIS

alpha(#) indicate the value of the dampening parameter; default is alpha(1)

dband(numlist) indicate the distance band or cut-off

cart use Cartesian coordinates (projected latitudes and longitudes)

r(#) indicate the earth radius value to be used in case of spherical coordinates;
default is r(6371.009), i.e. 6371.009 km

knn(#) request nearest neighbor spatial weights

econvar(1) request economic or inverse economic distance spatial weights

beta(#) specify the coefficient beta for the exponential function; default beta(1)

idvar(3) specify the identifier variable

dthres(#) set an absolute difference threshold

gamma(#) set the dampening parameter, in reminiscence to alpha

snn(#) generate socio-economic spatial weights based on the first # smaller absolute differences

dmins(1) generate a variable containing the minimum absolute difference for each observation

Other Options

xtw(#) generate spatial weights to be used with a balanced panel dataset

mataf save the spatial weights matrix and/or its eigenvalues to Mata file(s)

external make the spatial weights reside in Mata memory

eignval(eignv_name) place the eigenvalues of the spatial weights matrix into a column vector

eignvar(2) generate a variable to hold the eigenvalues of the spatial weights matrix

noisland remove observations with no neighbors when generating the spatial weights

rowstand row-standardize the spatial weights matrix

connect display connectivity information about the spatial weights matrix

xport(wght_filename, filetype) export the spatial weights matrix to a .dat, .txt, or a .gwt file

where filetype=dat|txt|gwt

replace overwrite existing 1, 2, and wght_filename as well as wght_name and eignv_name
if mataf specified

favor(speed|space) favor speed or space

Description

spwmatrix generates geographic distance based spatial weights and economic distance spatial weights based on an economic variable
(see Fingleton and Le Gallo, 2008) and social network and socio-economic spatial weights based on a
socio-economic variable (see Anselin and Bera, 1998). spwmatrix also imports pre-generated contiguity spatial weights
from ArcGIS (SWM file) and GeoDa (GAL file) or spatial weights from a .dta or a text (csv or tab delimited) file. Optionally,
created and imported spatial weights are exported to a .dat file for use in Matlab. Created spatial weights may also be exported
to a .gwt file for use in GeoDa. Ultimately, the requested spatial weights are delivered as a matrix loaded in Stata memory
(Stata object), as a matrix residing in Mata memory (Mata object), or as a permanent Mata file. When creating distance-related
spatial weights, spwmatrix uses either the straight-line (crow-fly) Euclidean distance or the Great Circle distance
depending on whether the latitudes and longitudes supplied in varlist are projected or not.

spwmatrix requires at least Stata 12.0

Main Options

wname(wght_name) specifies the name of the spatial weights matrix to be generated. This option is required.

wtype(bin|inv|econ|invecon|socnet|socecon) indicates whether binary, distance decay, economic distance, inverse economic distance,
social network, or socio-economic spatial weights should be created.

Refer to the literature cited below for a background on these spatial weights, except for inverse economic distance spatial
weights which are defined as:

W_ij = [1/|econvar_i - econvar_j +1|] * exp(-beta*D_ij) (1) , where D_ij is the distance between location i and location j

dta specifies that the spatial weights matrix to be imported is from a Stata .dta file.

text specifies that the spatial weights matrix to be imported is from a comma or tab delimited text file instead of the
default .gal file. The text file may or may not contain a header row with variable names. Although spwmatrix can determine for itself
whether a file is comma or tab delimited, it is recommended that the file name be specified with extension .csv or .txt. The same goes for
a .gal file.

swm(id_varname) indicates the name of the unique id variable (field) supplied to ArcGIS at the time of creation of the spatial weights matrix.
For more details on how to generate spatial weights in ArcGIS 9.3, click
here
and in ArcGIS 10, click here.
After generating the spatial weights matrix, you must use the Convert Spatial Weights Matrix To Table script from the Utilities toolbox
to convert the spatial weights matrix to a table. This process will generate a dbf file. For more details, click
here.
The dbf table will be added to the table of contents. Finally from ArcGIS, export the dbf table to a text (.csv) file. That .csv file can be imported
by spwmatrix. Should you need that the eigenvalues be computed, instead of ArcGIS, let spwmatrix row-standardize the spatial weights.

If none of dta, text, and swm() is specified, a .gal file from GeoDa will be assumed when the sub-command import is invoked.

Stop: When the import subcommand is invoked, spwmatrix assumes the dataset to carry the analysis is loaded and the user is
importing the spatial weights to proceed. The sort order for the observations used when you created the weights matrix must be the same for
the dataset. Otherwise, you will muck up the spatial relationship defined by the spatial weights matrix.

alpha(#) specifies the value to be used for the dampening parameter when requesting inverse distance spatial weights.
If wtype(inv) is specified, the default will be alpha(1). Specifying alpha(2) requests inverse distance squared spatial
weights.

dband(numlist) indicates the distance cut-off to be used. Beyond this cut-off, no spatial autocorrelation is assumed. This option is required
when option wtype(bin) is specified. Following the literature (see Boarnet et al., 2006), option dband(numlist) is not required when
an inverse distance weights matrix is requested. When dband(numlist) is specified, by default, the distance unit is assumed to be
kilometers, but that can be overridden with cart or r(#).

cart indicates that the latitudes and longitudes supplied in varlist are projected and that, in generating the spatial weights, Euclidean or
crow-fly distance should be calculated. By default, the Great Circle distance is calculated. For more details, see the help file for nearstat.

r(#) indicates the value to be used for the Earth radius or mean radius in case of spherical coordinates.
The Earth radius usually refers to various fixed distances and to various mean radii since only a sphere has a true radius.
Fortunately, the numerical differences among different radii vary by far less than one percent, making the choice of #
less of a concern.

N.B.: As indicated above, by default, the distance unit for dband(numlist) is assumed to be kilometers. If you want the unit to
be miles, then you must specify r(3958.761).

Options r(#) and cart may not be combined.

knn(#) requests nearest neighbor spatial weights and indicates the number of nearest neighbors to be used.
Option knn(#) may not be combined with either wtype() or dband().

econvar(1) specifies the name of the economic variable to be used in creating economic or inverse economic distance spatial weights.

beta(#) specifies the value to be used for the beta coefficient. The default is beta(1). You might want to choose # so that
the spatial weights matrix does not contain any rows with elements summing up to zero (the number of neighbors for each areal unit should
be at least one).

idvar(3) specifies the identifier variable with values varying from 1 to N, with N being the total number of observations. This option is
required when you specify wtype(socnet) to request a social network spatial weights matrix. The variable holding the groups or the networks
should be supplied with 2. For instance, you can generate spatial weights based on the idea that two households are considered neighbors
if they belong to the same village. In this case, 3 would contain the household identification numbers and 2 would take on the
village names or identification numbers. If your identifier variable does not vary from 1 to N, assuming your dataset is in the correct sort order,
you can easily generate one that does by coding:

. gen myidvar=_n

In a social network spatial weights matrix, the elements are defined as:

W_ij = 1 if i and j are neighbors and W_ij =0 otherwise (2)

In the case of socio-economic spatial weights requested by specifying wtype(socecon), 2 could be the name of the socio-economic
variable. The elements of the spatial weights matrix in this instance are defined by:

W_ij = [1/(diff_ij + 1)], where diff_ij=abs(2_i - 2_j) (3)

dthres(#) specify an absolute difference threshold beyond which no spatial autocorrelation is assumed. In this case, equation (3)
becomes:

W_ij = [1/(diff_ij + 1)] if diff_ij<=dthres and W_ij =0 otherwise (4)

gamma(#) specify a dampening parameter, in reminiscence to alpha() in the case of distance based weights matrix. The elements of the weights
matrix are now defined as:

W_ij = [1/(diff_ij + 1)^gamma] if diff_ij<=dthres and W_ij =0 otherwise (5)

snn(#) generate socio-economic spatial weights based on the first snn smaller absolute differences in a manner similar to
knn(#). In contrast to knn(#), snn(#) may be combined with wtype().

dmins(1) generate a variable containing the minimum absolute difference for each observation. This option may be helpful
in setting dthres(#). The maximum of those minimums will guarantee at least one neighbor.

Other Options

xtw(#) specifies the number of time periods (T) to generate spatial weights to be used with a balanced panel data. This option
assumes that the dataset is sorted by time and geoid and that the data for one is time period is kept to generate the spatial weights.
geoid is considered to be the identifier variable for the areal units.

mataf requests that the spatial weights - and its eigenvalues if eignval() is specified - be saved to permanent Mata file(s).
By default, the spatial weights matrix and its eigenvalues are created as Stata matrices temporarily loaded in memory. However, if the size of the
spatial weights matrix to be created or imported exceeds the matsize limit of your Stata flavor and option mataf is not specified, the
spatial weights matrix and its eigenvalues will automatically be saved to Mata files. In such a case, the names supplied with options wname()
and eignval() will be suffixed with "_n" to avoid replacing existing files. For instance, if you specify wname(mywght), then the Mata
file mywght_n will be created.

N.B.: Unless your goal is to generate a spatial weights matrix to be used with spatreg, in which case you should also specify
eignval(), I recommend specifying option mataf always.

external requests that the spatial weights matrix be stored as a Mata object residing in Mata memory.

eignval(eign_name) specifies that the spatial weights matrix eigenvalues be written to the N x 1 vector or file eign_name.

eignvar(2) specifies the name of a variable to hold the eigenvalues. This option must be specified if the spatial
weights matrix to be generated will be used to estimate spatial models using the spmlreg command.

N.B.: Before you specify the eignvar() option, be sure that the number of observations in your loaded dataset is the same as
the number of rows or columns in your spatial weights matrix. Otherwise, Stata will respond with a conformability error message.

noisland requests that island observations be removed so that the spatial weights matrix does not contain rows/columns with elements
summing up to zero. Note that spwmatrix does not delete those observations from the dataset. Rather, it simply lists them so that their
deletion remains at the sole discretion of the user.

N.B.: When option eignvar() is specified, if one of xtw() and noisland is also specified, then the eigenvalue variable
will be saved to a file and placed into the current directory. The file name will be the same as the name specified for the eigenvalue variable. An existing
file with the same name will be overwritten. The eigenvalue variable can be added to the estimation dataset by coding:

. merge 1:1 _n using filename

rowstand requests that the spatial weights matrix be row-standardized. spwmatrix will deny this request if elements of at least one
row sum up to zero. When this is the case, the indexes of such rows will be displayed, pointing to the observations with no neighbors.

connect requests that connectivity information such as sparseness, minimum and average number of neighbors, etc... for the generated
spatial weights matrix be displayed. Specifying this option is heartily recommended specifically when option beta(#) is specified. If the minimum number
of neighbors is zero, then you need to adjust your criteria.

xport(wght_filename, filetype) specifies that the spatial weights matrix (generated or imported) be written to the text file with
.dat format for use in Matlab, a .txt format for use with other Stata commands, or a .gwt format for other packages. Prior to using the
.gwt file in GeoDa, a header line containing 0, the number of observations, name of a shapefile, and the key variable should be inserted.
This can be done in Notepad. To use the .dat file in Matlab, you code:

load wght_filename.dat;

W=wght_filename(:,:);

replace overwrites existing 1, 2, and wght_filename as well as wght_name and eign_name if mataf is specified.

favor(speed|space) instructs spwmatrix to favor speed or space when performing all calculations.
favor(speed) is the default. This option provides a trade-off between speed and memory use. See [M-3] mata set.

Examples

1) Create a row-standardized binary spatial weights matrix assuming spherical coordinates and a distance cut-off of 10 miles

. spwmatrix gecon latitude longitude, wn(wbin) wtype(bin) db(0 10) ///

r(3958.761) row

2) Generate a spatial weights matrix as specified above, but save both the weights matrix and its eigenvalues to Mata files
wbin and eignwbin, and export the weights matrix to the text file wghtotxt.dat for use in Matlab

. spwmatrix gecon latitude longitude, wn(wbin) wtype(bin) dband(0 10) ///

r(3958.761) rowstand eignval(eignwbin) mataf matlab(wghtotxt)

3) Generate an inverse distance squared spatial weights matrix using projected latitudes and longitudes

. spwmatrix gecon latitude longitude, wname(winvsq) wtype(inv) ///

alpha(2) dband(0 100) cart

Here the distance cut-off unit is assumed to be the same as that of the projected latitudes and longitudes.

4) Generate an economic distance spatial weights matrix using employment as the economic variable

. spwmatrix gecon latitude longitude, wn(wecon) wtype(econ) ///

econvar(employment) rowstand

5) Generate an inverse economic distance spatial weights matrix using income as the economic variable

. spwmatrix gecon latitude longitude, wn(winvecon) wtype(invecon) econvar(income) rowstand

6) Import a first order contiguity spatial weights matrix created in GeoDa to be used in Stata

. spwmatrix import using C:\data\wcontig.gal, wname(wcontig) rowstand

As mentioned before, the .gal extension is required for spwmatrix to locate the file. Also, the identifier or key
variable supplied to GeoDa when you generate a contiguity spatial weights matrix should take on values ranging
from 1 to N, where N is the number of observations. But, the header line in the GeoDa .gal file needs not be removed.

7) Import a first order contiguity spatial weights matrix created in GeoDa and save it to a .dat file to be used in Matlab

. spwmatrix import using C:\data\wcontig.gal, wname(wcontig) xport(wcontig, dat)

8) Generate a row-standardized 5-nearest neighbor spatial weights matrix

. spwmatrix gecon latitude longitude, wname(wknn5) knn(5) rowstand

9) Generate a socio-economic spatial weights matrix

. spwmatrix socio socecon_var, wname(socecon_wght) row wtype(socecon)

10) Generate a social network spatial weights matrix (e.g., households are considered neighbors if they belong to the same village)

. spwmatrix socio village_id, wname(socnet_wght) wtype(socnet) idvar(hhid)

11) Import into Stata a spatial weights matrix created in ArcGIS and save it to a Mata file

. spwmatrix import using C:\data\wcontig.csv, wname(contigswm) swm(uniqid) mataf rowstand

where wcontig.csv is a file generated when exporting the converted table from ArcGIS.

12) Import into Stata a spatial weights matrix in .csv format and save it to a Mata file.

. spwmatrix import using C:\data\distspw.csv, wname(myswm_csv) mataf rowstand

where distspw.csv is a file generated by a spreadsheet.

References

Anselin, L, and A. Bera. 1998. "Spatial Dependence in Linear Regression Models with an Introduction to Spatial Econometrics."
In A. Ullah and D.E. Giles (Eds), Handbook of Applied Economic Statistics. New York: Marcel Dekker, pp.237-89.

Boarnet MG, Chalermpong S, Geho E. 2006 "Specification Issues in Models of Population and Employment Growth.
Papers in Regional Science 84: 21–46.

Fingleton. B. and J. Le Gallo. 2008. "Estimating Spatial Models with Endogenous Variables, a Spatial Lag and Spatially
Dependent Disturbances: Finite Sample Properties ", Papers in Regional Science 87(3): 319-339.

Wikipedia. 2008. Earth Radius. http://en.wikipedia.org/wiki/Earth_radius#Mean_radii.

-------- Great-Circle Distance. http://en.wikipedia.org/wiki/Great-circle_distance

Author

P. Wilner Jeanty, The Kinder Institute for Urban research/Hobby Center for the Study of Texas,
Rice University

Email to pwjeanty@rice.edu for any comments or suggestions.

Note: The previous version of spwmatrix was written when the author was a Research Economist
with the Department of Agricultural, Environmental, and Development Economics, The Ohio State University.

Citation

Users please cite this software as follows:

Jeanty, P.W., 2010. spwmatrix: Stata module to generate, import, and export spatial weights. Available from http://ideas.repec.org/c/boc/bocode/s457111.html.

Also see

Online: nearstat, spwmatfill, splagvar, anketest (if installed)