-------------------------------------------------------------------------------
help for splagvar 
-------------------------------------------------------------------------------

Title

  splagvar --- Generates spatially lagged variables, constructs the Moran
        scatter plot, and calculates global Moran's I statistics.

        +--------------------+
    ----+  Table of Contents +-----------------------------------------------

  Syntax
  General description
  Description of the options
  Examples
  References
  Author information
  Citation

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

Syntax

    splagvar [varlist1] [if] [in], [wname(weights_name) wfrom(Stata|Mata)
        ind(varlist2) Other_options]


    options                    Description
    -------------------------------------------------------------------------
    Options
 
      wname(weights_name)      indicate the name of the spatial weights
                                 matrix to be used

      wfrom(Stata|Mata)        indicate source of the spatial weights matrix
  
      ind(varlist2)            request spatially lagged explanatory variables

      order(#)                 indicate the lag order for the spatially
                                 lagged explanatory variables to be created

      equation(#)              generate spatially lagged variables for a
                                 specific equation

      plot(varname)            construct the Moran scatter plot

      title(title_info)        indicate a title for the Moran scatter plot

      saving(filename, ...)    save the graph to filename

      note(note_info)          provide notes about the graph

      reps(#)                  set the number of random permutations

      seed(#)                  specify a seed number

      moran(varname)           request Moran's I statistics

      qvar(varlist3)           generate quasi-instrumental variables

      qname(newvarlist)        provide names for the quasi-instrumental
                                 variables

      replace                  overwrite existing spatially lagged variables

      favor(speed|space)       favor speed or space when calculating the
                                 spatially lagged variables and the Moran's I
                                 statistics

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

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

    splagvar generates spatially lagged variables, constructs the Moran
    scatter plot, and calculates global Moran's I statistics to test for the
    presence of spatial dependence. The Moran's I p-value displayed on the
    Moran scatter plot is calculated using a random permutation procedure.
    Optionally, quasi-instruments can be generated. Unless quasi-instruments
    are requested, splagvar requires a spatial weights matrix which must have
    been created using spwmatrix or any other commands that generate spatial
    weights. The purpose of splagvar is to facilitate estimation by spatial
    two-stage least squares and generalized method of moments of spatial
    econometrics models in Stata (see the example section).

    While generated spatially lagged dependent variables are prefixed with
    wy_, generated first, second, and third order spatially lagged
    explanatory variables are prefixed with wx_, w2x_, and w3x_ respectively.
    The names of the supplied variables make up the remaining portions. If
    option equation(#) is specified, then the spatially lagged variables are
    prefixed with wy#_, wx#_, w2x#_, and w3x#_, where # stands for the
    equation number.

        splagvar requires Stata 10.1 or higher.

        +---------+
    ----+ Options +----------------------------------------------------------

    wname(weights_name) specifies the name of the spatial weights matrix to
        be used.

    wfrom(Stata | Mata) indicates whether the spatial weights matrix is a
        Stata matrix loaded in memory or a Mata file located in the working
        directory. When generated by spwmatrix the spatial weights matrix
        will exist as a Stata matrix or as a Mata file.

        wname() and wfrom() are required, unless qvar() and qname() are
        specified.

    ind(varlist2) specifies a list of explanatory variables whose spatial
        lags need to be taken. Variables deemed dependent or endogenous must
        be supplied in varlist1.

    order(#) specifies the spatial lag order (up to 3) for the spatially
        lagged explanatory variables to be created.  By default, first order
        spatial lags are calculated. For dependent or endogenous variables,
        only first order spatial lags may be generated.

    equation(#) indicates the number of the equation for which spatially
        lagged variables need to be calculated when generating variables for
        multiple equations.  For example, specifying equation(1) instructs
        Stata to generate spatially lagged variables for the first equation.
        This option is crucial for estimating a spatial simultaneous equation
        model where a different spatial weights matrix is used for each
        equation in Stata.

    plot(varname) constructs the Moran scatter plot for the dependent
        variable varname listed in varlist1.  On the plot are reported
        Moran's I statistics and the associated p-value based on a random
        permutation procedure.
 

    title(title_info) specifies a title for the Moran scatter plot.

    note(note_info) provides notes associated with the graph.

    saving(filename, ...) saves the graph to filename. Specifying the
        suboption replace with the option saving() will replace the graph if
        it already exists.

    seed(#) sets the random-number seed, which is defaulted to seed(042009).
        This option is useful to ensure replicability of the results.

    reps(#) specifies the number of random permutations to be performed. The
        default is reps(999).

    moran(varname) requests that global Moran's I statistics calculated under
        the assumptions of normal approximation and randomization be
        displayed. Again, varname must be from varlist1.

        N.B.: If varlist1 is not specified, none of the options plot(),
        saving(), title(), moran(), note(), reps(), and seed() may be
        specified.

    qvar(varlist3) specifies the variables to be used in generating
        quasi-instrumental variables.

    qname(newvarlist) specifies a list of variable names for the generated
        quasi-instrumental variables coded 1, 0, and -1 depending on whether
        or not the values of the corresponding variables specified with
        qvar() are in the upper, middle or lower third of values when placed
        in rank order (see Fingle and Le Gallo, 2008).

    replace overwrites existing spatially lagged or quasi-instrument
        variables.

    favor(speed|space) instructs splagvar to favor speed or space when
        calculating the spatially lagged variables or the Moran's I
        statistics.  favor(speed) is the default. This option provides a
        tradeoff between speed and memory use. See [M-3] mata set.

        +----------+
    ----+ Examples +---------------------------------------------------------

    1) Create a spatial lag for the dependent variable, construct the Moran
        scatter plot, and request Moran's I statistics

        . splagvar povrate, wname(C:\data/spweight) wfrom(Mata) plot(povrate)
        moran(povrate)


    2) Create a spatially lagged dependent variable and request Moran's I
        statistics and p-value under the assumption of normal approximation
        and randomization

        . splagvar crimerate, wname(spweight) wfrom(Stata) moran(crimerate)


    3) Create a spatially lagged dependent variable and first and second
        order spatially lagged independent variables

        . splagvar houseval, wname(spweight1) wfrom(Mata) ind(income
        population education) order(2)


    Now estimating a spatial lag model by spatial 2SLS and GMM using WX and
    (W^2)X as instruments has never been easier.

        . ivregress 2sls houseval (wy_houseval=wx_* w2x_*) income population
        education, vce(robust)

        . ivregress gmm houseval (wy_houseval=wx_* w2x_*) income population
        education


    Other endogenous variables can be added to the model provided that
    instruments are available.

        . ivregress gmm houseval (wy_houseval endogvar=wx_* w2x_*
        endogvar_instr) income population education


    Education can be considered endogenous if you can find a good instrument.

        . ivregress gmm houseval (wy_houseval education=wx_* w2x_*
        education_instr) income population


    Iterative GMM can be more efficient than two-step GMM.

        . ivregress gmm houseval (wy_houseval education=wx_* w2x_*
        education_instr) income population, igmm

    Note: If you want to use the lags of an instrumental variable as
    instruments, then you need to include it in varlist2


    4) Create a quasi-instrumental variable to be used as an instrument for
        education

        . splagvar, qvar(education) qname(educ_qinst)

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


References

Anselin, L. 2005. Exploring Spatial Data with GeoDaTM : A Workbook. Available a
> t:
http://www.csiss.org/clearinghouse/GeoDa/geodaworkbook.pdf

Anselin, L. 2007. "Spatial Econometrics". In T. C. Mills and K. Patterson (Eds)
> . Palgrave Handbook of Econometrics. Vol 1, 
Econometric Theory. New York: Palgrave MacMillan, pp. 901-969.

de Smith, M.J., M.F. Goodchild, and P.A. Longley. 2007. Geospatial Analysis: A 
> comprehensive Guide to Principles, Techniques, and Software Tools. 
Matador: Leicester, UK
http://www.spatialanalysisonline.com

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. 

Gould, W. 2006. "Mata Matters: Creating New Variables—Sounds Boring, Isn't". Th
> e Stata Journal 6: 112-123. 
Available from http://www.stata-journal.com/article.html?article=pr0021

Klotz, S. 2004. Cross-sectional Dependence in Spatial Econometrics Models: with
>  an Application to German Start-up Activity Data. 
Transaction Publishers, Piscataway, NJ.


Author

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

                        
    Email to pwjeanty@rice.edu

    N.B.: Previous versions of splagvar were written when the author was a
    Research Economist with the Dept. of Agricultural, Environmental, and
    Development Economics,
    The Ohio State University

Citation

Thanks for citing splagvar as follows:

Jeanty, P.W., 2010. splagvar: Stata module to generate spatially lagged variabl
> es, construct the Moran scatter plot, and calculate global Moran's I statisti
> cs
Available from http://ideas.repec.org/c/boc/bocode/s457112.html.


Also see

    Online: spwmatrix, spatgsa, spatcorr (if installed)