------------------------------------------------------------------------------- help for spwmatrix -------------------------------------------------------------------------------
Title
spwmatrix --- Generates, imports, and exports spatial weights
+--------------------+ ----+ Table of Contents +-----------------------------------------------
Syntax General description Description of the options Examples References Author information Citation
-------------------------------------------------------------------------------
Import first order contiguity spatial weights (GAL files) from GeoDa
spwmatrix gal using gal_filename, wname(wght_name) [Other_options]
Create geographic and economic distance-based spatial weights using latitude an > d longitude
spwmatrix gecon varlist [if] [in], wname(wght_name) [wtype(bin|inv|econ|invecon) cart r(#) dband(numlist) alpha(#) knn(#) econvar(varname1) beta(#) gwt(gwt_filename) connect Other_options]
Create social network and socio-economic spatial weights
spwmatrix socio varname2 [if] [in], wname(wght_name) wtype(socnet|socecon) [idvar(varname3) gwt(gwt_filename) connect Other_options]
where gal, gecon, and socio are sub-commands.
------------------------------------------------------------------------- Main Options wname(wght_name) indicate a name for the spatial weights matrix
wtype(bin|inv|econ|invecon|socnet|socecon) request binary, distance decay, economic distance, inverse economic distance, social network, or socio-economic spatial weights
alpha(#) indicate the value of the dampening parameter; default is alpha(1)
dband(numlist) indicate a 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(varname1) request economic or inverse economic distance spatial weights
beta(#) specify the coefficient beta for the exponential function
idvar(varname3) specify the identifier variable
gwt(gwt_filename) save the spatial weights in sparse form to a text file
connect display connectivity information about the spatial weights
------------------------------------------------------------------------- Other Options mataf save the spatial weights and the eigenvalues to Mata files
eignval(eignv_name) specify a column vector name to hold the eigenvalues
eignvar(newvar) specify a variable name to hold the eigenvalues
rowstand row-standardize the spatial weights
matlab(dat_filename) export the spatial weights to a .dat (text) file for use in Matlab
replace overwrite existing newvar, gwt_filename, and dat_filename as well as wght_name and eignv_name if mataf is specified
favor(speed|space) favor speed or space
-------------------------------------------------------------------------
+-------------+ ----+ Description +------------------------------------------------------
spwmatrix creates distance based spatial weights and imports first-order contiguity spatial weights (.gal files saved in sparse form) created using the GeoDa software (see http://geodacenter.asu.edu). spwmatrix also generates 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). 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 Stata matrix loaded in memory 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.
Spatial weights matrices created or imported by spwmatrix may be used by other user-written commands requiring a spatial weights matrix.
+--------------+ ----+ Main Options +-----------------------------------------------------
wname(wght_name) specifies a name for the spatial weights matrix to be created. 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|] * exp(-beta*D_ij), where D_ij is the distance between i and j
alpha(#) specifies a value to be used for the dampening parameter when requesting inverse distance spatial weights. If wtype(inv) is specified, the default will be alph(1). Specifying alpha(2) requests inverse distance squared spatial weights.
dband(numlist) indicates a distance cut-off to be used beyond which 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 overriden 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 specfiy 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(varname1) specifies the name of the economic variable to be used in creating economic or inverse economic distance spatial weights.
beta(#) specifies a value to be used for the beta coefficient. The default is beta(100). You might want to choose # so that the spatial weights matrix does not contain any rows with elements summing up to zero.
idvar(varname3) specifies the identifier variable (with values varying from 1 to N) to be used when creating social network spatial weights. The variable holding the groups or the networks should be supplied with varname2. idvar() is required when wtype(socnet) is specified to request social network spatial weights. For instance, you can generate spatial weights based on the idea that two or more households are considered neighbors if they belong to the same village. In this case, varname3 would contain the household indentification numbers and varname2 would take on the village names or identification numbers.
gwt(gwt_filename) requests that the generated spatial weights be written in sparse form to the text file gwt_filename.gwt for use in GeoDa. 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.
connect requests that connectivity information such as sparseness, average number of neighbors, etc... for the created spatial weights be displayed.
+---------------+ ----+ Other Options +----------------------------------------------------
mataf requests that the spatial weights (and the eigenvalues if eignval() is specified) be saved to permanent Mata files. By default, the spatial weights matrix and its eigenvalues are created as Stata matrices temporarily loaded in memory. However, if 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 suppplied with options wname() and eignval() will be suffixed with "_n" to avoid replacing existing files. For example, 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 a case you should also specify eignval(), I recommend specifying option mataf always.
eignval(eign_name) specifies that the spatial weights matrix eigenvalues be written to the N x 1 vector or file eign_name.
eignvar(newvar) specifies a variable name to hold the eigenvalues.
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 listed.
matlab(dat_filename) specifies that the spatial weights matrix (generated or imported) be written to the text file dat_filename.dat for use in Matlab. To use the file in Matlab, you code:
load dat_filename.dat;
W=dat_filename(:,:);
replace overwrites existing newvar, dat_filename, and gwt_filename and existing 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 tradeoff 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) dist(bin) db(0 10) /// r(3958.761) row
-----------------------------------------------------------------------------
2) Generate a spatial weights matrix under the assumptions above and 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
. spwmatrix gecon latitude longitude, wn(wbin) dist(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 gal using C:\data\wcontig.gal, wname(wcontig) rowstand
Note that the gal extension is required for spwmatrix to locate the file. Also, the identifier variable supplied to GeoDa when creating the spatial weights 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 gal using C:\data\wcontig.gal, wname(wcontig) matlab(wcontig)
-----------------------------------------------------------------------------
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 village_id, 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)
-----------------------------------------------------------------------------
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 Popu > lation 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_r > adii.
-------- Great-Circle Distance. http://en.wikipedia.org/wiki/Great-circle_dista > nce
P. Wilner Jeanty, Dept. of Agricultural, Environmental, and Development Economics, The Ohio State University
Email to jeanty.1@osu.edu for any comments or suggestions.
Users please cite this software as follows:
Jeanty, P.W., 2010. spwmatrix: Stata module to create, import, and export spati > al weights. Available from http://ideas.repec.org/c/boc/bocode/s457111.html.
Also see
Online: nearstat, spwmatfill, splagvar, anketest, and spatwmat (if installed)