{smcl}
{* 4oct2011}{É}
{cmd:help spgrid}{right:Version 1.0.1}
{hline}

{title:Title}

{p 4 11 2}
{hi:spgrid} {hline 2} Generates two-dimensional grids for spatial data analysis{p_end}


{marker syntax}{title:Syntax}

{p 8 15 2}
{cmd:spgrid} [{help using} {help spgrid##section03:{it:studyregion}}]
[{cmd:,}
{help spgrid##options1:{it:options}}]


{synoptset 35 tabbed}{...}
{marker options1}{synopthdr:{help spgrid##options2:options}{col 41}}
{synoptline}
{syntab : Main}
{synopt : {opt sh:ape(gcs)}}grid cell shape, where {it:gcs} is one of
   the following: {cmdab:he:xagonal} (default), {cmdab:sq:uare} {p_end}
{synopt : {cmdab:res:olution(a}{it:#}|{cmd:w}{it:#}{cmd:)}}grid
   resolution {p_end}
{synopt : {opt xd:im(#)}}number of grid columns {p_end}
{synopt : {opt yd:im(#)}}number of grid rows {p_end}
{synopt : {opt u:nit(string)}}grid unit of measurement {p_end}

{syntab : Rectangular study region}
{synopt : {opt xr:ange(xmin xmax)}}minimum and maximum coordinates of the
   horizontal side of the study region {p_end}
{synopt : {opt yr:ange(ymin ymax)}}minimum and maximum coordinates of the
   vertical side of the study region {p_end}

{syntab : Non-rectangular study region}
{synopt : {cmdab:mapid(}{help varname:{it:mapid}}{cmd:)}}set to {it:mapid}
   the name of the variable that, in the output dataset {it:gridpoints},
   stores the identifier of the study region polygon corresponding to each
   grid cell {p_end}
{synopt : {cmdab:mapex:clude(}{help spgrid##section03:{it:mapex}}{cmd:)}}exclude
   from the analysis the subareas of the study region defined in Stata dataset
   {it:mapex} {p_end}
{synopt : {opt idex:clude}}exclude subareas defined in dataset {it:mapex} on
   the basis of their identifier {p_end}

{syntab : Reporting}
{synopt : {opt d:ots}}display job progression dots {p_end}
{synopt : {opt noverb:ose}}suppress display of job progression {p_end}

{syntab: Saving results}
{p2coldent :* {cmdab:c:ells(}{help spgrid##section04:{it:gridcells}}{cmd:)}}save
   grid cells definition to Stata dataset {it:gridcells} {p_end}
{p2coldent :* {cmdab:p:oints(}{help spgrid##section04:{it:gridpoints}}{cmd:)}}save
   grid cells identifiers and grid points coordinates to Stata dataset
   {it:gridpoints} {p_end}
{synopt : {opt compress}}save only valid grid cells {p_end}
{synopt : {opt replace}}overwrite datasets {it:gridpoints} and
   {it:gridcells} if already existing {p_end}
{synoptline}
{p 4 6 2}* Required option {p_end}


{marker desc}{title:Description}

{pstd} {cmd:spgrid} generates two-dimensional grids that can be used by
       other Stata programs to carry out several kinds of spatial data
       analysis, e.g., kernel density and intensity estimation for
       two-dimensional spatial point patterns as implemented in the
       user-written Stata program {help spkde}. {p_end}

{pstd} In the context of spatial data analysis, a {it:grid} is a regular
       tessellation of a given two-dimensional study region that divides
       it into a set of contiguous {it:cells} whose centers are referred
       to as the {it:grid points} (Sahr {it:et al.} 2003).
       
{pstd} {cmd:spgrid} can generate both hexagonal and square grids, i.e.,
       grids whose cells are either hexagonal or square. In general,
       hexagonal grids have better properties than square grids. In
       particular, hexagonal cells offer a more compact tessellation
       of the plane, have a lower perimeter-to-area ratio {hline 1} which
       potentially reduces bias due to edge effects {hline 1} and have
       uniform adjacency, i.e., each of them has six adjacent neighbors in
       symmetrically equivalent positions (Sahr {it:et al.} 2003; de Sousa
       {it:et al.} 2006; Birch {it:et al.} 2007). {p_end}

{pstd} {cmd:spgrid} can generate grids covering both
       {help spgrid##section01:rectangular study regions} and 
       {help spgrid##section02:non-rectangular study regions}. The
       latter can be made of one or more polygons, and include
       one or more gaps {hline 1} i.e., subareas to be excluded
       from the analysis. {p_end}


{marker section01}{title:Rectangular study regions}

{pstd} To generate a grid covering a rectangular study region:
       {p_end}

{phang2}{space 1}o{space 2}Specify the size of the study region with options
                           {opt xrange(xmin xmax)} and {opt yrange(ymin ymax)}.
                           {p_end}

{phang2}{space 1}o{space 2}Specify the shape of the grid cells with option
                           {opt shape(gcs)}. {p_end}

{phang2}{space 1}o{space 2}Specify the size of the grid cells, either direcly
                           with option {cmd:resolution(a}{it:#}|{cmd:w}{it:#}{cmd:)},
                           or indirectly with one of options {opt xdim(#)} and
                           {opt ydim(#)}. {p_end}


{marker section02}{title:Non-rectangular study regions}

{pstd} To generate a grid covering a non-rectangular study region:
       {p_end}

{phang2}{space 1}o{space 2}Specify the {help spgrid##syntax:using} dataset
                           {help spgrid##section03:{it:studyregion}}, i.e.,
                           the dataset that defines the study region. {p_end}

{phang2}{space 1}o{space 2}Specify the shape of the grid cells with option
                           {opt shape(gcs)}. {p_end}

{phang2}{space 1}o{space 2}Specify the size of the grid cells, either direcly
                           with option {cmd:resolution(a}{it:#}|{cmd:w}{it:#}{cmd:)},
                           or indirectly with one of options {opt xdim(#)} and
                           {opt ydim(#)}. {p_end}

{phang2}{space 1}o{space 2}If needed, specify the subareas of the study region
                           to be excluded from the analysis with option
                           {cmd:mapexclude(}{help spgrid##section03:{it:mapex}}{cmd:)}
                           {hline 1} and, possibly, option {cmd:idexclude}. {p_end}


{marker section03}{title:Input datasets}

{pstd} As mentioned above, when requested to generate a grid covering a
       non-rectangular study region, {cmd:spgrid} requires that the
       {help spgrid##syntax:using} dataset {it:studyregion} be
       specified. Whenever the study region contains gaps {hline 1}
       i.e., subareas to be excluded from the analysis {hline 1} the
       dataset {it:mapex} must also be specified via option
       {opt mapexclude(mapex)}. {p_end}
 
{pstd} {it:studyregion} is a Stata dataset that contains the definition
       of the polygon(s) making up the study region of interest. Such
       definition must follow the format of a
       {help spmap##spatdata:spmap {it:basemap} dataset}. {p_end}

{pstd} {it:mapex} is a Stata dataset that contains the definition of the
       subareas of {it:studyregion} to be excluded from the analysis. Such
       definition must follow the format of a
       {help spmap##spatdata:spmap {it:basemap} dataset}. {p_end}


{marker section04}{title:Output datasets}

{pstd} {cmd:spgrid} routinely generates two Stata datasets that can then be
       used by other Stata programs to carry out several kinds of spatial
       data analysis: {it:gridcells} and {it:gridpoints}. {p_end}

{pstd} {it:gridcells} is a Stata dataset that contains the definition of the
       cells making up the grid. Its format corresponds to that of a
       {help spmap##spatdata:spmap {it:basemap} dataset}. {p_end}
 
{pstd} {it:gridpoints} is a Stata dataset that contains the identifiers of the
       grid cells and the coordinates of the corresponding grid
       points. Specifically, {it:gridpoints} includes the following
       variables: {p_end}

{phang2}{space 1}o{space 2}{bf:spgrid_id} is a numeric variable that uniquely
                           identifies the cells making up the grid. {p_end}

{phang2}{space 1}o{space 2}{bf:spgrid_xdim} is an integer variable that
                           identifies the x-dimension (column) of each
                           grid cell. {p_end}

{phang2}{space 1}o{space 2}{bf:spgrid_ydim} is an integer variable that
                           identifies the y-dimension (row) of each
                           grid cell. {p_end}

{phang2}{space 1}o{space 2}{bf:spgrid_status} is an indicator variable that
                           takes value 1 when the corresponding grid cell is
                           valid {hline 1} i.e., lies within the study region
                           {hline 1} and value 0 otherwise. {p_end}

{phang2}{space 1}o{space 2}{bf:spgrid_xcoord} is a numeric variable that
                           contains the x-coordinate of each grid point.
                           {p_end}

{phang2}{space 1}o{space 2}{bf:spgrid_ycoord} is a numeric variable that
                           contains the y-coordinate of each grid point.
                           {p_end}

{phang2}{space 1}o{space 2}{it:mapid} is a numeric variable {hline 1}
                           specified via option {opt mapid(mapid)}
                           {hline 1} that contains the identifier of the
                           study region polygon corresponding to each
                           grid cell. {p_end}


{marker options2}{title:Options}

{dlgtab:Main}

{phang}
{opt shape(gcs)} specifies the shape of the grid cells.

{phang2}{cmd:shape(hexagonal)} is the default and requests that the
   grid cells be hexagonal. {p_end}

{phang2}{cmd:shape(square)} requests that the grid cells be square. {p_end}

{phang}
{cmd:resolution(a}{it:#}|{cmd:w}{it:#}{cmd:)} specifies the resolution
   of the grid, i.e., the size of the grid cells. {p_end}

{phang2}{cmd:resolution(a}{it:#}{cmd:)} requests that the grid cells
   have area {it:#}. {p_end}

{phang2}{cmd:resolution(w}{it:#}{cmd:)} requests that the grid cells
   have width {it:#}. When option {cmd:shape(hexagonal)} is specified,
   the cell width corresponds to the diameter of the circle inscribed
   in the hexagon. When option {cmd:shape(square)} is specified, the
   cell width corresponds to the length of the side of the square. {p_end}

{phang}
{opt xdim(#)} specifies the number of grid columns. {p_end}

{phang}
{opt ydim(#)} specifies the number of grid rows. {p_end}

{phang}
{opt unit(string)} specifies the unit of measurement (e.g., miles,
   kilometers, meters, pixels) of the grid. The default is a generic
   {cmd:unit(units)}. {p_end}

{dlgtab:Rectangular study region}

{phang}
{opt xrange(xmin xmax)} specifies the minimum ({it:xmin}) and the
   maximum ({it:xmax}) coordinates of the horizontal side of the
   study region. {p_end}

{phang}
{opt yrange(ymin ymax)} specifies the minimum ({it:ymin}) and the
   maximum ({it:ymax}) coordinates of the vertical side of the
   study region. {p_end}


{dlgtab:Non-rectangular study region}

{phang}
{opt mapid(mapid)} specifies the name of the numeric variable that, in
   dataset {help spgrid##section04:{it:gridpoints}}, will contain the
   identifier of the study region polygon corresponding to each grid
   cell. The default is {cmd:mapid(spgrid_mapid)}. {p_end}

{phang}
{opt mapexclude(mapex)} requests that the subareas of the study region defined
   in dataset {help spgrid##section03:{it:mapex}} be excluded from the
   analysis. {p_end}

{phang}
{cmd:idexclude} requests that the subareas of the study region defined with
   option {opt mapexclude(mapex)} be excluded from the analysis not on the
   basis of their geometry (the default), but on the basis of their
   identifier. {p_end}

{dlgtab:Reporting}

{phang}
{cmd:dots} requests that job progression dots be displayed. {p_end}

{phang}
{cmd:noverbose} requests that the display of every indicator of job
   progression be suppressed. {p_end}

{dlgtab:Saving results}

{phang}
{opt cells(gridcells)} requests that the definition of the grid cells be
   saved to dataset {help spgrid##section04:{it:gridcells}}. {p_end}

{phang}
{opt points(gridpoints)} requests that the identifiers of the grid cells
   and the coordinates of the corresponding grid points be saved to dataset
   {help spgrid##section04:{it:gridpoints}}. {p_end}

{phang}
{opt compress} requests that only the valid grid cells be saved to
   datasets {help spgrid##section04:{it:gridcells}} and
   {help spgrid##section04:{it:gridpoints}}. {p_end}

{phang}
{opt replace} requests that datasets {help spgrid##section04:{it:gridcells}}
   and {help spgrid##section04:{it:gridpoints}} be overwritten if already
   existing. {p_end}


{title:Examples}
{cmd}
    . spgrid, xrange(0 500) yrange(0 200) resolution(w10)   ///
        cells("GridCells.dta") points("GridPoints.dta")     ///
        replace dots
    . use "GridPoints.dta", clear
    . spmap using "GridCells.dta", id(spgrid_id)

    . spgrid, xrange(0 500) yrange(0 200) shape(square) xdim(50)   ///
        cells("GridCells.dta") points("GridPoints.dta")            ///
        replace dots
    . use "GridPoints.dta", clear
    . spmap using "GridCells.dta", id(spgrid_id)

    . spgrid using "Italy-OutlineCoordinates.dta",   ///
        resolution(w10) unit(kilometers)             ///
        cells("Italy-GridCells.dta")                 ///
        points("Italy-GridPoints.dta")               ///
        replace dots
    . use "Italy-GridPoints.dta", clear
    . spmap using "Italy-GridCells.dta", id(spgrid_id)   ///
        polygon(data("Italy-OutlineCoordinates.dta")     ///
        ocolor(red) osize(thick))

    . spgrid using "Italy-OutlineCoordinates.dta",   ///
        resolution(w10) unit(kilometers)             ///
        cells("Italy-GridCells.dta")                 ///
        points("Italy-GridPoints.dta")               ///
        replace compress dots
    . use "Italy-GridPoints.dta", clear
    . spmap using "Italy-GridCells.dta", id(spgrid_id)   ///
        polygon(data("Italy-OutlineCoordinates.dta")     ///
        ocolor(red) osize(medthick))

    . spgrid using "Italy-OutlineCoordinates.dta",   ///
        resolution(w10) unit(kilometers)             ///
        mapexclude("Italy-Exclude.dta")              ///
        cells("Italy-GridCells.dta")                 ///
        points("Italy-GridPoints.dta")               ///
        replace compress dots
    . use "Italy-GridPoints.dta", clear
    . spmap using "Italy-GridCells.dta", id(spgrid_id)   ///
        polygon(data("Italy-OutlineCoordinates.dta")     ///
        ocolor(red) osize(medthick))
{txt}

{title:Author}

{p 4} Maurizio Pisati {p_end}
{p 4} Department of Sociology and Social Research {p_end}
{p 4} University of Milano Bicocca - Italy {p_end}
{p 4} {browse "mailto:maurizio.pisati@unimib.it":maurizio.pisati@unimib.it}


{title:References}

{p 4 8 2}Birch, C.P.D., Oom, S.P. and J.A. Beecham. 2007. Rectangular and
         Hexagonal Grids Used for Observation, Experiment and Simulation in
         Ecology. {it:Ecological Modelling} 206: 347{c -}359.

{p 4 8 2}de Sousa, L., Nery, F., Sousa, R. and J. Matos. 2006. Assessing the
         Accuracy of Hexagonal versus Square Tiled Grids in Preserving DEM
         Surface Flow Directions. In {it:Proceedings of the 7th International}
         {it:Symposium on Spatial Accuracy Assessment in Natural Resources}
         {it:and Environmental Sciences}, 5{c -}7 July, Lisboa, Portugal,
         ed. M. Caetano and M. Pinho, 191{c -}200.

{p 4 8 2}Sahr, K., White, D. and A.J. Kimerling. 2003. Geodesic Discrete
         Global Grid Systems. {it:Cartography and Geographic Information}
         {it:Science} 30: 121{c -}134.


{title:Also see}

{psee}
Online:  {helpb spkde} (if installed), {helpb spmap} (if installed)
{p_end}