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

## Description

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

## Usage

 `1` ```hal.point(x, n, J = NULL, bases = c(2, 3)) ```

## Arguments

 `x` A `SpatialPoints` or `SpatialPointsDataFrame` object. This object must contain at least 1 point. `n` Sample size. Number of locations to draw from the set of points 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)` 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. `bases` 2X1 vector of Halton bases. These must be co-prime.

## Details

A brief description of Halton Lattice sampling for points: Given a set of Halton Lattice parameters `J` and `bases`, a lattice of Halton boxes is constructed over the bounding box of the input points. This results in `prod(bases^J)` Halton boxes on the bounding box. The Halton index of all boxes is computed and assigned to points that lie in each box. Points that lie in the same Halton box are randomly assigned unique Halton cycle numbers. This separates points in the same Halton box by at least `prod(bases^J)` units when indices are mapped to the real line. Finally, a random number between 1 and the largest Halton (index+cycle) is drawn, and the next `n` units in the mapped real numbers are taken as the sample, restarting from the beginning if necessary.

## 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 that 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 the Halton indices for the Halton boxes containing the point, after adding random cycles to 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.

• `HaltonIndex`: The index of the Halton box containing the point. This column is not, in general, unique. Points with the same `HaltonIndex` are in the same Halton box, and are "close" in space.

• `geometryID`: The ID of the sampled point in `x` The ID of points in `x` are `row.names(x)`.

• Any attributes of the original points (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., "point").

• `sample.type`: Type of sample drawn. (i.e., "HAL").

• `J`: Exponents of the bases used to form the lattice of Halton boxes. This is either the input `J`, or the `J` vector computed by `halton.indices`.

• `bases`: Bases of the Halton sequence used to draw the sample.

• `hl.box`: The bounding box around points in `x` used to draw the sample. See `halton.indices`.

• `random.start`: The random start of the sample in the 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. This is a random number between 0 and the number of points in `x` minus 1 . The sample consists of the `n` consecutive units starting at `random.start+1` in the sorted Halton frame.

## Author(s)

Trent McDonald

`hal.line`, `hal.polygon`, `sdraw`, `bas.point`
 ```1 2 3 4 5 6 7 8``` ```# Draw sample of Hawaii coastline # This takes approximately 30 seconds to run data(WA.cities) samp <- hal.point( WA.cities, 100 ) # Different lattice topology samp <- hal.point( WA.cities, 100, J=c(10,4)) ```