*! version 1.40 17 June 2021
version 1.40. 17 June 2021

Title

spgen -- Generate Spatially Lagged Variables

(View PDF manual online)

Syntax

spgen varlist [if] [in], lon(varname) lat(varname) swm(swmtype) dist(#) dunit(km|mi) [options]

* lon(varname) specifies the variable of longitude.

* lat(varname) specifies the variable of latitude.

* swm(swmtype) specifies a type of the spatial weight matrix.

* dist(#) specifies the threshold distance for the spatial weight matrix.

* dunit(km|mi) specifies the unit of distance (km, kilometers; mi, miles).

order(#) uses #th order of the spatial weight matrix.

wvar(varname) specifies a weight variable for the spatial weight matrix.

rowif(varname) specifies an indicator variable for targeted observations.

suffix(string) appends a suffix to names of output variables.

nostd specifies non row-standardized spatial weight matrix.

nomatsave does not save the bilateral distance matrix and spatial weight matrix on the memory.

dms converts DMS format to decimal format.

approx uses distance based on the simplified version of the Vincenty formula.

detail displays descriptive statistics of distance.

largesize is suited for large sized data.

replace overwrites the existing outcome variables in the dataset.

* lat(), lon(), swm(), dist(), and dunit()
are required.

Description

spgen generates the spatially lagged variables of varlist.

Outcome

spgen generates the spatially lagged variables, splag#_varname_swmtype[_wvar][suffix], on the dataset.

o # of splag# is automatically inserted in accordance with order(#).

o varname is automatically inserted for each of varlist.

o swmtype is automatically inserted from either b for swm(pow), k for swm(knn #), e for swm(exp #), or p for swm(pow #) in accordance with swm(swmtype).

o wvar is optionally inserted as th name of weight variable when specified.

o suffix is optionally inserted as user specified string when specified.

Options

lon(varname) specifies the variable of longitude in the dataset. The decimal format is expected in the default setting. The positive value denotes the east longitude. The negative value denotes the west longitude.

lat(varname) specifies the variable of latitude in the dataset. The decimal format is expected in the default setting. The positive value denotes the north latitude. The negative value denotes the south latitude.

swm(swmtype) specifies a type of the spatial weight matrix. One of the following four types of spatial weight matrix must be specified: bin (binary), knn (k-nearest neighbor), exp (exponential), or pow (power). The parameter k must be specified for the k-nearest neighbor as a natural number (k = 1, 2, 3, ...) as follows: swm(knn #). The distance decay parameter # must be specified for the exponential and power functional types of spatial weight matrix as follows: swm(exp #) and swm(pow #). The bilateral distance is calculated by Vincenty formula (Vincenty, 1975).

dist(#) specifies the threshold distance for the spatial weight matrix. This option is ignored if the swm(knn #) option is specified.

dunit(km|mi) specifies the unit of distance. Either km (kilometers) or mi (miles) must be specified.

order(#) uses #th order of spatial weight matrix. The default setting calculates the 1st order of spatially lagged variable.

wvar(varname) specifies a weight variable for the spatial weight matrix. A weight variable is not used in the default setting.

rowif(varname) specifies an indicator variable that takes the value 1 for targeted observations for which users calculate spatially lagged variables and 0 otherwise. The default setting returns spatially lagged variables for all observations in the dataset. It takes much time in large size dataset. The rowif() option allows to users to calculate spatially lagged variables for subset of observations. The rowif() option is not used in the default setting.

suffix(string) appends a suffix to names of output variables. It is helpful when spgen is used in foreach or forvalues. The suffix(string) option is not used in the default setting.

nostd uses the spatial weight matrix that is not row-standardized during the calculation process. The row-standardized spatial weight matrix is used in the default setting.

nomatsave does not save the bilateral distance matrix r(D) and spatial weight matrix r(W) on the memory. It is used to save memory space for a low spec computer. The nomatsave option is not used in the default setting.

dms converts the DMS (Degrees, Minutes, Seconds) format to a decimal format. The default setting is the decimal format.

approx uses bilateral distance approximated by the simplified version of the Vincenty formula. The approx option is not used in the default setting.

detail displays descriptive statistics of distance. The detail option is not used in the default setting.

largesize is suited for large-sized data. When this option is specified, nomatsave, approx, and order(1) options are automatically applied. The detail option displays only minimum and maximum distances. The largesize option is not used in the default setting.

replace is used to overwrite the existing output variables in the dataset. The replace option is not used in the default setting.

Examples: baseline

See Kondo (2017) for the dataset used in this example.

Spatially lagged variable using power functional type of spatial weight matrix

. spgen CRIME, lat(y_cntrd) lon(x_cntrd) swm(pow 8) dist(.) dunit(km)

Spatially lagged variable using exponential functional type of spatial weight matrix

. spgen CRIME, lat(y_cntrd) lon(x_cntrd) swm(exp 0.15) dist(.) dunit(km)

Spatially lagged variable using binary type of spatial weight matrix

. spgen CRIME, lat(y_cntrd) lon(x_cntrd) swm(bin) dist(5) dunit(km)

Spatially lagged variable using k-nearest neighbor type of spatial weight matrix

. spgen CRIME, lat(y_cntrd) lon(x_cntrd) swm(knn 1) dist(.) dunit(km)

Examples: multiple variables

spgen accepts multiple variables (spgen ver. 1.40 or later).

. spgen CRIME INC HOVAL, lat(y_cntrd) lon(x_cntrd) swm(pow 1) dist(.) dunit(km)

Examples: nostd option

nostd option is helpful for the calculation of market potential (spgen ver. 1.10 or later).

. spgen gdp, lat(y_cntrd) lon(x_cntrd) swm(pow 1) dist(.) dunit(km) nostd

. gen mp = gdp + splag1_gdp_p

Examples: rowif() option

rowif() option is helpful if users calculate spatially lagged variables for particular observations (spgen ver. 1.40 or later).

. gen d_rowif = (id_state == 13)

. spgen gdp, lat(y_cntrd) lon(x_cntrd) swm(pow 1) dist(.) dunit(km) nostd rowif(d_rowinf)

Examples: largesize option

largesize option is helpful for large size datasets, such as 10,000 observations or more (spgen ver. 1.30 or later). This option avoids matrix manipulations during the calculation process.

. spgen CRIME, lat(y_cntrd) lon(x_cntrd) swm(pow 1) dist(.) dunit(km) large

Examples: replace option

replace option is helpful to avoid error message of overwriting the existing output variables.

. spgen CRIME, lat(y_cntrd) lon(x_cntrd) swm(pow 1) dist(.) dunit(km) replace

Stored results

spgen stores the following in r().

Scalars
r(N) number of observations

r(K) number of variables

r(td) threshold distance

r(dd) parameter k for swm(knn #) or distance decay parameter for swm(exp #) and swm(pow #)

r(od) order of spatial lag

r(dist_mean) mean of distance

r(dist_sd) standard deviation of distance

r(dist_min) minimum value of distance

r(dist_max) maximum value of distance

Macros
r(cmd) spgen

r(varlist) variable names

r(swm) type of spatial weight matrix

r(swm_std) row-standardization of spatial weight matrix

r(dunit) unit of distance

r(dist_type) exaxt of approximation of Vincenty formula

r(weight) variable name specified in wvar() option

r(wtype) type of weight in wvar() option

r(rowif) variable name specified in rowif() option

Matrices
r(D) lower triangle of distance matrix

r(W) spatial weight matrix

Author

Keisuke Kondo

Research Institute of Economy, Trade and Industry (RIETI). Tokyo, Japan.

METI Annex 11F, 1-3-1 Kasumigaseki, Chiyoda-ku, Tokyo, 100-8901, Japan.

(URL: https://keisukekondokk.github.io/)

References

Kondo, K. (2017) "Introduction to spatial econometric analysis: Creating spatially lagged variable in Stata,"
Mimeo. (URL: https://keisukekondokk.github.io/software/doc/spgen.pdf)

Vincenty, T. (1975) "Direct and inverse solutions of geodesics on the ellipsoid with application of nested equations," Survey Review 23(176), pp. 88-93.

Disclaimer

(a) Keisuke Kondo makes the utmost effort to maintain, but nevertheless does not guarantee, the accuracy, completeness, integrity, usability, and recency of spgen.

(b) Keisuke Kondo and any organization to which Keisuke Kondo belongs hereby disclaim
responsibility and liability for any loss or damage that may be incurred by users as a result
of using spgen. Keisuke Kondo and any organization to which Keisuke Kondo belongs are neither responsible nor liable for any loss or damage that users of spgen may cause to any third party as a result of using spgen.

(c) spgen may be modified, moved or deleted without prior notice.