Title
spgrid -- Generates two-dimensional grids for spatial data analysis
spgrid [using studyregion] [, options]
options Description ------------------------------------------------------------------------- Main shape(gcs) grid cell shape, where gcs is one of the following: hexagonal (default), square resolution(a#|w#) grid resolution xdim(#) number of grid columns ydim(#) number of grid rows unit(string) grid unit of measurement
Rectangular study region xrange(xmin xmax) minimum and maximum coordinates of the horizontal side of the study region yrange(ymin ymax) minimum and maximum coordinates of the vertical side of the study region
Non-rectangular study region mapid(mapid) set to mapid the name of the variable that, in the output dataset gridpoints, stores the identifier of the study region polygon corresponding to each grid cell mapexclude(mapex) exclude from the analysis the subareas of the study region defined in Stata dataset mapex idexclude exclude subareas defined in dataset mapex on the basis of their identifier
Reporting dots display job progression dots noverbose suppress display of job progression
Saving results * cells(gridcells) save grid cells definition to Stata dataset gridcells * points(gridpoints) save grid cells identifiers and grid points coordinates to Stata dataset gridpoints compress save only valid grid cells replace overwrite datasets gridpoints and gridcells if already existing ------------------------------------------------------------------------- * Required option
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 spkde.
In the context of spatial data analysis, a grid is a regular tessellation of a given two-dimensional study region that divides it into a set of contiguous cells whose centers are referred to as the grid points (Sahr et al. 2003).
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 - which potentially reduces bias due to edge effects - and have uniform adjacency, i.e., each of them has six adjacent neighbors in symmetrically equivalent positions (Sahr et al. 2003; de Sousa et al. 2006; Birch et al. 2007).
spgrid can generate grids covering both rectangular study regions and non-rectangular study regions. The latter can be made of one or more polygons, and include one or more gaps - i.e., subareas to be excluded from the analysis.
To generate a grid covering a rectangular study region:
o Specify the size of the study region with options xrange(xmin xmax) and yrange(ymin ymax).
o Specify the shape of the grid cells with option shape(gcs).
o Specify the size of the grid cells, either direcly with option resolution(a#|w#), or indirectly with one of options xdim(#) and ydim(#).
To generate a grid covering a non-rectangular study region:
o Specify the using dataset studyregion, i.e., the dataset that defines the study region.
o Specify the shape of the grid cells with option shape(gcs).
o Specify the size of the grid cells, either direcly with option resolution(a#|w#), or indirectly with one of options xdim(#) and ydim(#).
o If needed, specify the subareas of the study region to be excluded from the analysis with option mapexclude(mapex) - and, possibly, option idexclude.
As mentioned above, when requested to generate a grid covering a non-rectangular study region, spgrid requires that the using dataset studyregion be specified. Whenever the study region contains gaps - i.e., subareas to be excluded from the analysis - the dataset mapex must also be specified via option mapexclude(mapex). 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 spmap basemap dataset.
mapex is a Stata dataset that contains the definition of the subareas of studyregion to be excluded from the analysis. Such definition must follow the format of a spmap basemap dataset.
spgrid routinely generates two Stata datasets that can then be used by other Stata programs to carry out several kinds of spatial data analysis: gridcells and gridpoints.
gridcells is a Stata dataset that contains the definition of the cells making up the grid. Its format corresponds to that of a spmap basemap dataset. gridpoints is a Stata dataset that contains the identifiers of the grid cells and the coordinates of the corresponding grid points. Specifically, gridpoints includes the following variables:
o spgrid_id is a numeric variable that uniquely identifies the cells making up the grid.
o spgrid_xdim is an integer variable that identifies the x-dimension (column) of each grid cell.
o spgrid_ydim is an integer variable that identifies the y-dimension (row) of each grid cell.
o spgrid_status is an indicator variable that takes value 1 when the corresponding grid cell is valid - i.e., lies within the study region - and value 0 otherwise.
o spgrid_xcoord is a numeric variable that contains the x-coordinate of each grid point.
o spgrid_ycoord is a numeric variable that contains the y-coordinate of each grid point.
o mapid is a numeric variable - specified via option mapid(mapid) - that contains the identifier of the study region polygon corresponding to each grid cell.
+------+ ----+ Main +-------------------------------------------------------------
shape(gcs) specifies the shape of the grid cells.
shape(hexagonal) is the default and requests that the grid cells be hexagonal.
shape(square) requests that the grid cells be square.
resolution(a#|w#) specifies the resolution of the grid, i.e., the size of the grid cells.
resolution(a#) requests that the grid cells have area #.
resolution(w#) requests that the grid cells have width #. When option shape(hexagonal) is specified, the cell width corresponds to the diameter of the circle inscribed in the hexagon. When option shape(square) is specified, the cell width corresponds to the length of the side of the square.
xdim(#) specifies the number of grid columns.
ydim(#) specifies the number of grid rows.
unit(string) specifies the unit of measurement (e.g., miles, kilometers, meters, pixels) of the grid. The default is a generic unit(units).
+--------------------------+ ----+ Rectangular study region +-----------------------------------------
xrange(xmin xmax) specifies the minimum (xmin) and the maximum (xmax) coordinates of the horizontal side of the study region.
yrange(ymin ymax) specifies the minimum (ymin) and the maximum (ymax) coordinates of the vertical side of the study region.
+------------------------------+ ----+ Non-rectangular study region +-------------------------------------
mapid(mapid) specifies the name of the numeric variable that, in dataset gridpoints, will contain the identifier of the study region polygon corresponding to each grid cell. The default is mapid(spgrid_mapid).
mapexclude(mapex) requests that the subareas of the study region defined in dataset mapex be excluded from the analysis.
idexclude requests that the subareas of the study region defined with option mapexclude(mapex) be excluded from the analysis not on the basis of their geometry (the default), but on the basis of their identifier.
+-----------+ ----+ Reporting +--------------------------------------------------------
dots requests that job progression dots be displayed.
noverbose requests that the display of every indicator of job progression be suppressed.
+----------------+ ----+ Saving results +---------------------------------------------------
cells(gridcells) requests that the definition of the grid cells be saved to dataset gridcells.
points(gridpoints) requests that the identifiers of the grid cells and the coordinates of the corresponding grid points be saved to dataset gridpoints.
compress requests that only the valid grid cells be saved to datasets gridcells and gridpoints.
replace requests that datasets gridcells and gridpoints be overwritten if already existing.
Examples
. 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))
Author
Maurizio Pisati Department of Sociology and Social Research University of Milano Bicocca - Italy maurizio.pisati@unimib.it
References
Birch, C.P.D., Oom, S.P. and J.A. Beecham. 2007. Rectangular and Hexagonal Grids Used for Observation, Experiment and Simulation in Ecology. Ecological Modelling 206: 347-359.
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 Proceedings of the 7th International Symposium on Spatial Accuracy Assessment in Natural Resources and Environmental Sciences, 5-7 July, Lisboa, Portugal, ed. M. Caetano and M. Pinho, 191-200.
Sahr, K., White, D. and A.J. Kimerling. 2003. Geodesic Discrete Global Grid Systems. Cartography and Geographic Information Science 30: 121-134.
Also see
Online: spkde (if installed), spmap (if installed)