generatePolygonSamplePoints: generatePolygonSamplePoints - Create sample points for a set...

In bmcgaughey1/HexSampleR: Create Sample Points For Polygon(s)

generatePolygonSamplePoints – Create sample points for a set of polygon

Description

Generate a set of sample points within a polygon. Given an input polygon, create a set of sample points within the polygon. Multi-part polygons are allowed but the number of sample points will be distributed over the parts.

Usage

generatePolygonSamplePoints(
  inputPolygons,
  IDColumnLabel = "",
  appendAttributes = FALSE,
  columnNameID = "",
  pattern = "hexagonal",
  polyBuffer = -1,
  gridSpacing = 5000,
  offset = c(0.5, 0.5),
  count = -1,
  perturb = FALSE,
  perturbMultiplier = 0.5,
  minArea = -1,
  seedColumnLabel = "",
  seed = -1,
  verbose = 0
)

Arguments

inputPolygons	Spatial* or sf object containing the polygon(s) for which you want sample points.
IDColumnLabel	Character: Name of the column in the inputPolygons data to be used to build the identifier for the sample points. If not specified, identifiers for the sample points are simple sequential numbers starting at 1. The same sequence of identifiers is generated for all polygons so you should set appendAttributes to TRUE to ensure you have enough information to uniquely identify each sample point when not specifying IDColumnLabel.
appendAttributes	Logical: if TRUE, the fields for the inputPolygons are appended to the fields of the returned point data. If FALSE, only a label field is added to the fields of the return points. The label field is named Label unless columnNameID is specified.
columnNameID	Character: Name for the identifier field in the set of sample points. If not specified, the name will be "Label".
pattern	Character indicating the desired sample pattern. pattern will be passed to spsample(). Choices are: "random" for completely spatial random; "regular" for regular (systematically aligned) sampling; and "hexagonal" for sampling on a hexagonal lattice. While other options are available in (and will be passed to) spsample(), their behavior as used in this application is unknown. If "random" is specified, you must also specify count.
polyBuffer	Distance to reduce the size of the polygon(s) by applying rgeos::gbuffer with width = -polyBuffer. A value <= 0 will produce no buffer.
gridSpacing	Desired grid size passed to spsample().
offset	Position of the regular sample grid in the unit cell ⁠[0,1] x [0,1]⁠. The default is c(0.5,0.5) placing the position of the grid at the center of the sample cell. When pattern = "regular", the effect of offset is easy to interpret. However, when pattern = "hexagonal" or pattern = "random", the effect of offset is much harder to interpret.
count	Desired number of sample points. You may not actually get back count points depending on the interaction between the polygon shape, buffer and count). If between 0 and 1, count is interpreted as a proportion of the number of sample points generated that should be returned. This is useful when generating sample points for polygons that vary in size. count should be the desired number of sample points when pattern is "random".
perturb	Logical: If TRUE, point locations are randomly moved from the location generated by spsample(). The distance moved is controlled by perturbMultiplier * gridSpacing.
perturbMultiplier	Multiplier > 0 used to adjust locations generated by spsample().
minArea	Minimum area for polygons used to create sample points. This is the total area covered by the feature so it might include several polygons. The area is evaluated before and after the buffer is applied. If -1 (default), the minimum area is computed as gridSpacing^2 * 5. If 0, sampling will be attempted for all features. However, sample generation may fail for small features depending on the values for buffer and gridSpacing.
seedColumnLabel	Character: Name of the column in inputPolygons containing an integer value used to initialize the random number generator. Using a field unique to a polygon allows you to generate a consistent sample every time a particular polygon is used. When seedColumnLabel is not specified, a single seed value (if provided in seed) is used for all polygons. If a seed value is not provided in seed, the random number generator is not seeded.
seed	Seed for the random number generator to be applied before any sample generation (outside the loop used to generate sample locations for each polygon in inputPolygons).
verbose	if > 0, output status information every verbose features in inputPolygons.

Details

There are 3 potential interactions between gridSpacing and count: Both have values > 0: gridSpacing controls the sample point spacing. If the number of sample points exceeds count, the set of points is sampled to produce count points. count > 0; gridSpacing = -1: point spacing is computed using count and the polygon area. count = -1; gridSpacing > 0: gridSpacing controls the sample point spacing and you get all sample points.

The number of sample points may not exactly match count due to irregularities in the the polygon. If count is between 0 and 1, it is interpreted as the proportion of the sample points that should be returned. For example, if you want a 10 percent sample of the points located on a 100 meter grid, set count = 0.1 and gridSpacing = 100.

If you perturb the locations without using a polyBuffer, you can end up with points outside the polygon. The final set of sample points is intersected with the original polygon so the points outside the polygon are eliminated. However, this final clipping operation can mess up the count (number of sample points). This may not be a problem when gridSpacing and count have values (not = -1) because the sampling to reduce the number of points (if needed) occurs after the clipping operation.

One caution with polyBuffer: If you specify a value for polyBuffer larger than the width of a polygon, you can essentially remove the polygon so you end up with no sample points. This is especially a problem when you have project polygons made up of several parts and some of the parts are small. Units for the buffer are the same as the horizontal units for the input feature so you shouldn't use data in LON-LAT with units of degrees.

You can call this function with multiple polygons to generate a set of sample points for each polygon. Each set will have count points (at least the logic tries to generate count points).

Value

A set of sample point locations attributed with X, Y, and an identifier created using either IDColumnLabel and the sequential point number (when IDColumnLabel is specified) or just the sequential point number (when IDColumnLabel is not specified) and all columns from the inputPolygons data frame. The return type will be determined by the type of inputPolygons. If inputPolygons is a Spatial* type, the return will be a SpatialPointsDataFrame object and if inputPolygons is a simple features (sf) type, the return will be a simple features (sf) type.

bmcgaughey1/HexSampleR documentation built on July 1, 2024, 10:02 p.m.