{É}
help spgridVersion 1.0.1

Title

spgrid -- Generates two-dimensional grids for spatial data analysis

Syntax

spgrid [using studyregion]
[,
options]

options

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

Description

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.

Rectangular study regions

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(#).

Non-rectangular study regions

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.

Input datasets

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.

Output datasets

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.

Options

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)