hal.line: Draws a Halton Lattice sample from a linear (line) resource .

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

View source: R/hal.line.r


Draws a Halton Lattice sample from a SpatialLines* object.


hal.line(x, n, J = NULL, eta = c(1, 1), bases = c(2, 3), balance = "1D",
  frame.spacing = NULL)



A SpatialLines or SpatialLinesDataFrame object. This object must contain at least 1 line. If it contains more than 1 line, the HAL sample is drawn from the union of all lines.


Sample size. Number of locations to draw from the set of all lines contained in x.


A 2X1 vector of base powers. J[1] is for horizontal, J[2] for vertical dimension. J determines the size and shape of the smallest Halton boxes. There are bases[1]^J[1] vertical columns of Halton boxes over x's bounding box, and bases[2]^J[2] horizontal rows of Halton boxes over the bounding box, for a total of prod(bases^J) total boxes. The dimension of each box is c(dx,dy)/(bases^J), where c(dx,dy) are the horizontal and vertical extents of x's bounding box. If J=NULL (the default), J is chosen so that Halton boxes are as square as possible.


When balance is "2D", eta is a 2X1 vector specifying the number of points to add in the horizontal and vertical dimensions of each Halton box. e.g., if eta = c(3,2), a grid of 3 (horizontal) by 2 (vertical) points is added inside each Halton box. Size and shape of Halton boxes is controlled by J parameter.


If balance == "2D", this is a 2X1 vector of co-prime Halton bases. If balance == "1D", this is the single (scalar) Halton base to use. If length(bases) == 2 and balance == "1D", the first element of bases is used.


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 the appear in x and a 1-dimensional BAS sample is taken from the amalgamated line. Sample locations are then mapped back to two dimensional space and appear on the original lines. This method maintains 1D spatial balance, but not 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 bas.point). This maintains 2D spatial balance of sample locations on the lines, but is slower than "1D".


If balance == "2D", this is the desired spacing of points on lines prior to sampling via HAL. If balance == "2D", the first step is discretization of lines by placing equally-spaced points on all lines. Then, points are sampled using Halton sampling (see hal.point) for points. This parameter controls spacing of points during the discretization of lines. For example, specifying 50, and assuming x is projected to UTM meters, means points will be placed every 50 meters along all lines in x before sampling. x should be projected before sampling so that pt.spacing makes sense. If pt.spacing is not specified and balance == "2D", 1000*n points will be placed along all lines during discretization.


A HAL sample is drawn from the union of all lines in x by discretization of lines using points spaced pt.spacing apart. The discretized points are then sampled using the HAL method for points (see hal.point).


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

  • sampleID: A unique identifier for every sample point. This encodes the HAL order. return[order(return$sampleID),] will sort the returned object in HAL order. sampleID's, in the HAL case, are not consecutive. sampleID's are usually the Halton indices for the Halton boxes containing the point, after adding random cycles for multiple points in the same box (see halton.frame). If the sample cycled around to the beginning of the frame, because random start fell at the end, the sample number is appended to the beginning of the normal sampleID's so they will sort the frame in the proper 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",

  • random.start: The random start of the sample in the 1D or 2D Halton frame. The Halton frame is a list of all points sorted in Halton order. Halton order is the Halton index of each point, with random cycles added to multiple points in the same Halton box. If balance=="2D", this is a random number between 0 and the number of points in the discretization of x (see frame.spacing). If balance=="1D", this is a random number between 0 and the number of points in the 1D Halton lattice discretization of x (see parameters J and eta). The sample consists of the n consecutive units starting at random.start+1 in the sorted Halton frame.


Trent McDonald

See Also

bas.line, hal.point, hal.polygon, sdraw


# Default sample of Hawaii coastline. 1D balance
samp <- hal.line( HI.coast, 100 )

# Desire frame with spacing = 500 meters
# Frame has ~3144 points = lineLength(HI.coast)/500 
samp <- hal.line( HI.coast, 100, balance="2D", frame.spacing=500)
# Desire 2000 points in frame
# Set frame.spacing = lineLength / 2000 
# Set Halton lattice to contain  
#    2592 boxes = prod(c(2,3)^c(5,4))  
samp <- hal.line( HI.coast, 100, J=c(5,4), balance="2D", 

SDraw documentation built on May 19, 2017, 4:13 p.m.
Search within the SDraw package
Search all R packages, documentation and source code

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.

Please suggest features or report bugs in the GitHub issue tracker.

All documentation is copyright its authors; we didn't write any of that.