# hal.line: Draws a Halton Lattice sample from a linear (line) resource . In SDraw: Spatially Balanced Sample Draws for Spatial Objects

## Description

Draws a Halton Lattice sample from a `SpatialLines*` object.

## Usage

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

## Arguments

 `x` 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. `n` Sample size. Number of locations to draw from the set of all lines contained in `x`. `J` 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. `eta` 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. `bases` 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. `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 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". `frame.spacing` 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.

## Details

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`).

## Value

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.

## Author(s)

Trent McDonald

`bas.line`, `hal.point`, `hal.polygon`, `sdraw`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14``` ```# 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", frame.spacing=lineLength(HI.coast)/2000) ```