R: sample point locations in (or on) a spatial object

spsample {sp} | R Documentation

## sample point locations in (or on) a spatial object

### Description

sample point locations within a square area, a grid, a polygon, or on a spatial line, using regular or random sampling methods; the methods used assume that the geometry used is not spherical, so objects should be in planar coordinates

### Usage

    spsample(x, n, type, ...)
    makegrid(x, n = 10000, nsig = 2, cellsize, offset = rep(0.5, nrow(bb)),
    	pretty = TRUE)

### Arguments

`x` | Spatial object; `spsample(x,...)` is a generic method for the existing `sample.Xxx` functions
`...` | optional arguments, passed to the appropriate `sample.Xxx` functions; see NOTES for `nclusters` and `iter`
`n` | (approximate) sample size
`type` | character; `"random"` for completely spatial random; `"regular"` for regular (systematically aligned) sampling; `"stratified"` for stratified random (one single random location in each "cell"); `"nonaligned"` for nonaligned systematic sampling (nx random y coordinates, ny random x coordinates); `"hexagonal"` for sampling on a hexagonal lattice; `"clustered"` for clustered sampling; `"Fibonacci"` for Fibonacci sampling on the sphere (see references).
`bb` | bounding box of the sampled domain; setting this to a smaller value leads to sub-region sampling
`offset` | for square cell-based sampling types (regular, stratified, nonaligned, hexagonal): the offset (position) of the regular grid; the default for `spsample` methods is a random location in the unit cell [0,1] x [0,1], leading to a different grid after each call; if this is set to `c(0.5,0.5)`, the returned grid is not random (but, in Ripley's wording, "centric systematic"). For line objects, a single offset value is taken, where the value varies within the [0, 1] interval, and 0 is the beginning of each Line object, and 1 its end
`cellsize` | if missing, a cell size is derived from the sample size `n`; otherwise, this cell size is used for all sampling methods except `"random"`
`nsig` | for "pretty" cell size; `spsample` does not result in pretty grids
`pretty` | logical; if `TRUE`, choose pretty (rounded) coordinates

### Value

an object of class SpatialPoints-class. The number of points is only guaranteed to equal `n` when sampling is done in a square box, i.e. (`sample.Spatial`). Otherwise, the obtained number of points will have expected value `n`.

When `x` is of a class deriving from Spatial-class for which no spsample-methods exists, sampling is done in the bounding box of the object, using `spsample.Spatial`. An overlay using over may be necessary to select the features inside the geometry afterwards.

Sampling type `"nonaligned"` is not implemented for line objects.

Some methods may return NULL if no points could be successfully placed.

`makegrid` makes a regular grid that covers `x`; when `cellsize` is not given it derives one from the number of grid points requested (approximating the number of cells). It tries to choose pretty cell size and grid coordinates.

### Methods

x = "Spatial"

  sample in the bbox of `x`

x = "Line"

  sample on a line

x = "Polygon"

  sample in a Polygon

x = "Polygons"

  sample in a Polygons object, consisting of possibly multiple Polygon objects (holes must be correctly defined, use `checkPolygonsHoles` if need be)

x = "SpatialPolygons"

  sample in an SpatialPolygons object; sampling takes place over all Polygons objects present, use subsetting to vary sampling intensity (density); holes must be correctly defined, use `checkPolygonsHoles` if need be

x = "SpatialGrid"

  sample in an SpatialGrid object

x = "SpatialPixels"

  sample in an SpatialPixels object

### Note

If an Polygon-class object has zero area (i.e. is a line), samples on this line element are returned. If the area is very close to zero, the algorithm taken here (generating points in a square area, selecting those inside the polygon) may be very resource intensive. When numbers of points per polygon are small and type="random", the number searched for is inflated to ensure hits, and the points returned sampled among these.

The following two arguments can be further specified:

`nclusters` Number of clusters (strata) to sample from.

`iter`(default = 4) number of times to try to place sample points in a polygon before giving up and returning NULL - this may occur when trying to hit a small and awkwardly shaped polygon in a large bounding box with a small number of points

### Author(s)

Edzer Pebesma, edzer.pebesma@uni-muenster.de

### References

Chapter 3 in B.D. Ripley, 1981. Spatial Statistics, Wiley

Fibonacci sampling: Alvaro Gonzalez, 2010. Measurement of Areas on a Sphere Using Fibonacci and Latitude-Longitude Lattices. Mathematical Geosciences 42(1), p. 49-64

### See Also

over, point.in.polygon, sample

### Examples

    data(meuse.riv)
    meuse.sr = SpatialPolygons(list(Polygons(list(Polygon(meuse.riv)), "x")))

    plot(meuse.sr)
    points(spsample(meuse.sr, n = 1000, "regular"), pch = 3)

    plot(meuse.sr)
    points(spsample(meuse.sr, n = 1000, "random"), pch = 3)

    plot(meuse.sr)
    points(spsample(meuse.sr, n = 1000, "stratified"), pch = 3)

    plot(meuse.sr)
    points(spsample(meuse.sr, n = 1000, "nonaligned"), pch = 3)

    plot(meuse.sr)
    points(spsample(meuse.sr@polygons[[1]], n = 100, "stratified"), pch = 3, cex=.5)

    data(meuse.grid)
    gridded(meuse.grid) = ~x+y
    image(meuse.grid)
    points(spsample(meuse.grid,n=1000,type="random"), pch=3, cex=.5)
    image(meuse.grid)
    points(spsample(meuse.grid,n=1000,type="stratified"), pch=3, cex=.5)
    image(meuse.grid)
    points(spsample(meuse.grid,n=1000,type="regular"), pch=3, cex=.5)
    image(meuse.grid)
    points(spsample(meuse.grid,n=1000,type="nonaligned"), pch=3, cex=.5)

    fullgrid(meuse.grid) = TRUE
    image(meuse.grid)
    points(spsample(meuse.grid,n=1000,type="stratified"), pch=3,cex=.5)

[Package sp version 1.4-0 Index]