-------------------------------------------------------------------------------

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

spwmatrixgalusinggal_filename,wname(wght_name)[Other_options]

Create geographic and economic distance-based spatial weights using latitude an > d longitude

spwmatrixgeconvarlist[if] [in],wname(wght_name)[wtype(bin|inv|econ|invecon)cartr(#)dband(numlist)alpha(#)knn(#)econvar(varname1)beta(#)gwt(gwt_filename)connectOther_options]

Create social network and socio-economic spatial weights

spwmatrixsociovarname2[if] [in],wname(wght_name)wtype(socnet|socecon)[idvar(varname3)gwt(gwt_filename)connectOther_options]

where

gal, gecon, and socioare 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 isalpha(1)

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

cartuse 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

connectdisplay connectivity information about the spatial weights

------------------------------------------------------------------------- Other Options

matafsave 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

rowstandrow-standardize the spatial weights

matlab(dat_filename)export the spatial weights to a .dat (text) file for use inMatlab

replaceoverwrite existingnewvar,gwt_filename, anddat_filenameas well aswght_nameandeignv_nameifmatafis specified

favor(speed|space)favor speed or space-------------------------------------------------------------------------

+-------------+ ----+ Description +------------------------------------------------------

spwmatrixcreates 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).spwmatrixalso 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,spwmatrixuses either the straight-line (crow-fly) Euclidean distance or the Great Circle distance depending on whether the latitudes and longitudes supplied invarlistare projected or not.Spatial weights matrices created or imported by

spwmatrixmay 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. Ifwtype(inv)is specified, the default will bealph(1). Specifyingalpha(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 optionwtype(bin)is specified. Following the literature (see Boarnet et al., 2006) , optiondband(numlist)is not required when an inverse distance weights matrix is requested. Whendband(numlist)is specified, by default, the distance unit is assumed to be kilometers, but that can be overriden withcartorr(#).

cartindicates that the latitudes and longitudes supplied invarlistare 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 fornearstat.

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 fordband(numlist)is assumed to be kilometers. If you want the unit to be miles, then you must specfiyr(3958.761).Options

r(#)andcartmay not be combined.

knn(#)requests nearest neighbor spatial weights and indicates the number of nearest neighbors to be used. Optionknn(#)may not be combined with eitherwtype()ordband().

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 isbeta(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 withvarname2.idvar()is required whenwtype(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,varname3would contain the household indentification numbers andvarname2would 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 filegwt_filename.gwtfor 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.

connectrequests that connectivity information such as sparseness, average number of neighbors, etc... for the created spatial weights be displayed.

+---------------+ ----+ Other Options +----------------------------------------------------

matafrequests that the spatial weights (and the eigenvalues ifeignval()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 optionmatafis not specified, the spatial weights matrix and its eigenvalues will automatically be saved to Mata files. In such a case, the names suppplied with optionswname()andeignval()will be suffixed with "_n" to avoid replacing existing files. For example, if you specifywname(mywght), then the Mata filemywght_nwill be created.

N.B.:Unless your goal is to generate a spatial weights matrix to be used withspatreg, in which a case you should also specifyeignval(), I recommend specifying optionmatafalways.

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

eignvar(newvar)specifies a variable name to hold the eigenvalues.

rowstandrequests that the spatial weights matrix be row-standardized.spwmatrixwill 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 filedat_filename.datfor use in Matlab. To use the file in Matlab, you code:

load dat_filename.dat;

W=dat_filename(:,:);

replaceoverwrites existingnewvar,dat_filename, andgwt_filenameand existingwght_nameandeign_nameifmatafis specified.

favor(speed|space)instructsspwmatrixto 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

wbinandeignwbin, and export the weights matrix to the text filewghtotxt.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) cartHere 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) rowstandNote that the gal extension is required for

spwmatrixto 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 Science84: 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 UniversityEmail 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 seeOnline:

nearstat,spwmatfill,splagvar,anketest, andspatwmat(if installed)