bas.line: Draws a Balanced Acceptance Sample (BAS) from a linear...
In semmons1/TEST-SDraw: Spatially Balanced Samples of Spatial Objects

Description Usage Arguments Details Value Author(s) See Also Examples

Draws a BAS sample from a SpatialLines* object.

1	bas.line(x, n, balance = "1D", init.n.factor = 10)

`x`	A `SpatialLines` or `SpatialLinesDataFrame` object. This object must contain at least 1 line. If it contains more than 1 line, the BAS sample is drawn from the union of all lines.
`n`	Sample size. Number of locations to draw from the set of all lines contained in `x`.
`balance`	Option specifying how spatial balance is maintained. The options are "1D" or "2D". Under "1D" all lines in `x` are stretched straight and laid end-to-end in the order they appear in `x` and a 1-dimensional BAS sample is taken from the amalgamated line. 1D sample locations on the amalgamated line are mapped back to two dimensional space for output and appear on the original lines. This method maintains 1D spatial balance, but not necessarily 2D balance. Spatially balanced samples in 1D may not look spatially balanced when plotted in 2 dimensions. Under "2D" a systematic sample of points along the union of all lines in `x` is drawn first, and a 2-dimensional BAS sample of the points is drawn (see `init.n.factor` below and `bas.point`). This maintains 2D spatial balance of sample locations on the lines. Depending on `init.n.factor`, the "2D" balance option can take significantly longer to run than the "1D" option.
`init.n.factor`	If `balance == "2D"`, this is a scalar controlling the number of points to place on the lines before drawing the 2D BAS sample. Number of points created on the line is `ninit.n.factor`, so this number can grow quickly. On average, this is the number of un-selected points between each selected point. See Details. If one desires an underlying grid spaced w meters apart, set `init.n.factor` to L/(wn), where L is total length of all lines in `x` and n is sample size.

If a "1D" sample is requested, spatial balance is maintained on the lines when laid end-to-end in the order they appear. Points far apart in 1 dimension may be close together in 2 dimensions, and vice versa. Thus the sample may not look spatially balanced on a 2D map. This is a true infinite sample in that any of an infinite number of points along the lines could be selected.

If a "2D" BAS sample is requested, spatial balance is maintained in 2 dimensions. Points are well balance on a 2D map. This is done by discretization of lines with a dense systematic sample of points (with random start) where density of the systematic points is controlled by init.n.factor. After discretization of the line, points are selected using bas.point. The BAS method for points places a small square (pixel) around each and samples the set of squares using the BAS method for polygons (see bas.polygon). The BAS method of polygons computes Halton points until n fall inside the squares surrounding discretization points. When a Halton point falls in a square, the square is selected and the sample location is the center of the square (which falls somewhere on the original lines).

A SpatialPointsDataFrame containing locations in the BAS sample, in BAS order. Attributes of the sample points are:

sampleID: A unique identifier for every sample point. This encodes the BAS order. If BAS order is lost, return[ order( return$sampleID ),] will resort the returned object (i.e., return) into BAS order.
geometryID: The ID of the line in x on which each sample point falls. The ID of lines in x are row.names(x).
Any attributes of the original lines (in x).

Additional attributes of the output object, beyond those which make it a SpatialPointsDataFrame, are:

frame: Name of the input sampling frame.
frame.type: Type of resource in sampling frame. (i.e., "line").
sample.type: Type of sample drawn. (i.e., "BAS").
balance: The type of balance ("1d" or "2d").
random.start: The random seed for the random-start 1D or 2D Halton sequence that produced the sample. If balance=="1D", this is a single uniform random integer between 0 and maxU. If balance=="2D", this is a vector of two uniform random integers between 0 and maxU.
bas.bbox: If balance=="2D", this is the bounding box surrounding x used to scale Halton points. The scaled Halton sequence is bas.bbox[,"min"]+ t(halton(n,2,random.start))* rep(max( diff(t(bas.bbox))), 2). If balance=="1D", this is a vector containing the 1D bounding box. Lower limit of the 1D bounding box is 0. Upper limit of the 1D box is the total length of lines in x. In this case, Halton points are scaled as bas.bbox[,"min"]+ halton(n,1,random.start)* diff(bas.bbox) which is equivalent to halton(n,1, random.start)* bas.bbox[2] because bas.bbox[1] is zero.

Trent McDonald

bas.line, bas.polygon, sdraw

#   Draw sample of Hawaii coastline
#   This takes approximately 60 seconds to run
samp <- bas.line( HI.coast, 50 )
plot(HI.coast)
points( samp, pch=16, col="red" )