trap.builder {secr} | R Documentation

## Complex Detector Layouts

### Description

Construct detector layouts comprising small arrays (clusters) replicated across space, possibly at a probability sample of points.

### Usage

    trap.builder (n = 10, cluster, region = NULL, frame = NULL,
        method = c("SRS", "GRTS", "all", "rank"),
        edgemethod = c("clip", "allowoverlap", "allinside", "anyinside", "centreinside"),
        samplefactor = 2, ranks = NULL, rotation = NULL, detector,
        exclude = NULL, exclmethod = c("clip", "alloutside", "anyoutside", "centreoutside"),
        plt = FALSE, add = FALSE)

    mash (object, origin = c(0,0), clustergroup = NULL, ...)

    cluster.counts (object)

    cluster.centres (object)

### Arguments

`n` | integer number of clusters (ignored if method = "all")
`cluster` | traps object
`region` | bounding polygon
`frame` | data frame of points used as a finite sampling frame
`method` | character string (see Details)
`edgemethod` | character string (see Details)
`samplefactor` | oversampling to allow for rejection of edge clusters (multiple of n)
`ranks` | vector of relative importance (see Details)
`rotation` | angular rotation of each cluster about centre (degrees)
`detector` | character detector type (see `detector`)
`exclude` | polygon(s) from which detectors are to be excluded
`exclmethod` | character string (see Details)
`plt` | logical: should array be plotted?
`add` | logical: add to existing plot
`object` | single-session multi-cluster capthist object, or traps object for `cluster.centres`
`origin` | new coordinate origin for detector array
`clustergroup` | list of vectors subscripting the clusters to be mashed
`...` | other arguments passed by mash to make.capthist (e.g., sortrows)

### Details

The detector array in `cluster` is replicated `n` times and translated to centres sampled from the area sampling frame in `region` or the finite sampling frame in `frame`. Each cluster may be rotated about its centre either by a fixed number of degrees (`rotation` positive), or by a random angle (`rotation` negative).

If the `cluster` argument is not provided then single detectors of the given type are placed according to the design.

The sampling frame is finite (the points in `frame`) whenever `frame` is not NULL. If `region` and `frame` are both specified, sampling uses the finite frame but sites may be clipped using the polygon.

`region` and `exclude` may be a two-column matrix or dataframe of x-y coordinates for the boundary, or a SpatialPolygons or SpatialPolygonsDataFrame object from sp. A SpatialPolygons object is mostly sufficient, but a full SpatialPolygonsDataFrame object is required for `region` when `method = "GRTS"` and `frame = NULL`.

`method` may be "SRS", "GRTS", "all" or "rank". "SRS" takes a simple random sample (without replacement in the case of a finite sampling frame). "GRTS" takes a spatially representative sample using the ‘generalized random tessellation stratified’ (GRTS) method of Stevens and Olsen (2004). "all" replicates `cluster` across all points in the finite sampling frame. "rank" selects `n` sites from `frame` on the basis of their ranking on the vector ‘ranks’, which should have length equal to the number of rows in `frame`; ties are resolved by drawing a site at random.

Options for `edgemethod` are –

`edgemethod` | Description
`"clip"` | reject any individual detectors outside `region`
`"allowoverlap"` | no action
`"allinside"` | reject whole cluster if any component is outside `region`
`"anyinside"` | reject whole cluster if no component is inside `region`
`"centreinside"` | reject whole cluster if centre outside `region`, and clip to `region`

Similarly, `exclmethod` may be "clip" (reject individual detectors), "alloutside" (reject whole cluster if any component is outside `exclude`) etc. Sufficient additional samples (`(samplefactor--1) * n`) must be drawn to allow for replacement of any rejected clusters; otherwise, an error is reported (‘not enough clusters within polygon’).

The package sp is required. GRTS samples require function `grts` in package spsurvey of Olsen and Kincaid. Much more sophisticated sampling designs may be specified by using `grts` directly.

`mash` collapses a multi-cluster capthist object as if all detections were made on a single cluster. The new detector coordinates in the ‘traps’ attribute are for a single cluster with (min(x), min(y)) given by `origin`. `clustergroup` optionally selects one or more groups of clusters to mash; if `length(clustergroup) > 1` then a multisession capthist object will be generated, one ‘session’ per clustergroup. By default, all clusters are mashed.

`mash` discards detector-level covariates and occasion-specific ‘usage’, with a warning.

`cluster.counts` returns the number of distinct individuals detected per cluster in a single-session multi-cluster capthist object.

`cluster.centres` returns the centroid of the detector locations in each cluster. When clusters have been truncated these differ from the attribute `centres` set by `make.systematic`.

### Value

`trap.builder` produces an object of class ‘traps’.

`method = "GRTS"` causes messages to be displayed regarding the stratum (always "None"), and the initial, current and final number of levels from the GRTS algorithm.

`plt = TRUE` causes a plot to be displayed, including the polygon or finite sampling frame as appropriate.

`mash` produces a capthist object with the same number of rows as the input but different detector numbering and ‘traps’. An attribute ‘n.mash’ is a vector of the numbers recorded at each cluster; its length is the number of clusters. An attribute ‘centres’ is a dataframe containing the x-y coordinates of the cluster centres. The `predict` method for secr objects and the function `derived` both recognise and adjust for mashing.

`cluster.counts` returns a vector with the number of individuals detected at each cluster.

`cluster.centres` returns a dataframe of x- and y-coordinates.

### Note

The function `make.systematic` should be used to generate systematic random layouts. It calls `trap.builder`.

The sequence number of the cluster to which each detector belongs, and its within-cluster sequence number, may be retrieved with the functions `clusterID` and `clustertrap`.

### References

Stevens, D. L., Jr., and Olsen, A. R. (2004) Spatially-balanced sampling of natural resources. Journal of the American Statistical Association 99, 262–278.

### See Also

`make.grid`, `traps`, `make.systematic`, `clusterID`, `clustertrap`

### Examples

    ## solitary detectors placed randomly within a rectangle
    tempgrid <- trap.builder (n = 10, method = "SRS",
        region = cbind(x = c(0,1000,1000,0),
        y = c(0,0,1000,1000)), plt = TRUE)

    ## GRTS sample of mini-grids within a rectangle
    ## GRTS requires package 'spsurvey' that may be unavailable
    ##  on Mavericks
    ## edgemethod = "allinside" avoids truncation at edge
    minigrid <- make.grid(nx = 3, ny = 3, spacing = 50,
        detector = "proximity")

    if (requireNamespace('spsurvey')) {
      tempgrid <- trap.builder (n = 20, cluster = minigrid,
        method = "GRTS", edgemethod = "allinside", region =
        cbind(x = c(0,6000,6000,0), y = c(0,0,6000,6000)),
        plt = TRUE)
    }
    ## as before, but excluding detectors from a polygon
    if (requireNamespace('spsurvey')) {
      tempgrid <- trap.builder (n = 40, cluster = minigrid,
        method = "GRTS", edgemethod = "allinside", region =
        cbind(x = c(0,6000,6000,0), y = c(0,0,6000,6000)),
        exclude = cbind(x = c(3000,7000,7000,3000), y =
        c(2000,2000,4000,4000)), exclmethod = "alloutside",
        plt = TRUE)
    }

    ## one detector in each 100-m grid cell -
    ## a form of stratified simple random sample
    origins <- expand.grid(x = seq(0, 900, 100),
        y = seq(0, 1100, 100))
    XY <- origins + runif(10 * 12 * 2) * 100
    temp <- trap.builder (frame = XY, method = "all",
        detector = "multi")
    ## same as temp <- read.traps(data = XY)
    plot(temp, border = 0)  ## default grid is 100 m

    ## simulate some data
    ## regular lattice of mini-arrays
    minigrid <- make.grid(nx = 3, ny = 3, spacing = 50,
        detector = "proximity")
    tempgrid <- trap.builder (cluster = minigrid , method =
        "all", frame = expand.grid(x = seq(1000, 5000, 2000),
        y = seq(1000, 5000, 2000)), plt = TRUE)
    tempcapt <- sim.capthist(tempgrid, popn = list(D = 10))
    cluster.counts(tempcapt)
    cluster.centres(tempgrid)

    ## "mash" the CH
    summary(mash(tempcapt))

    ## compare timings (estimates are near identical)
    ## Not run:
    tempmask1 <- make.mask(tempgrid, type = "clusterrect",
        buffer = 200, spacing = 10)
    fit1 <- secr.fit(tempcapt, mask = tempmask1, trace = FALSE)         ## 680 s

    tempmask2 <- make.mask(minigrid, spacing = 10)
    fit2 <- secr.fit(mash(tempcapt), mask = tempmask2, trace = FALSE)   ## 6.2 s
    ## density estimate is adjusted automatically
    ## for the number of mashed clusters (9)

    predict(fit1)
    predict(fit2)
    fit1$proctime
    fit2$proctime

    ## End(Not run)

    ## two-phase design: preliminary sample across region,
    ## followed by selection of sites for intensive grids
    ## Not run:
    arena <- data.frame(x = c(0,2000,2000,0), y = c(0,0,2500,2500))
    t1 <- make.grid(nx = 1, ny = 1)
    t4 <- make.grid(nx = 4, ny = 4, spacing = 50)
    singletraps <- make.systematic (n = c(8,10), cluster = t1,
        region = arena)
    CH <- sim.capthist(singletraps, popn = list(D = 2))
    plot(CH, type = "n.per.cluster", title = "Number per cluster")
    temp <- trap.builder(10, frame = traps(CH), cluster = t4,
        ranks = cluster.counts(CH), method = "rank",
        edgemethod = "allowoverlap", plt = TRUE, add = TRUE)

    ## End(Not run)

[Package secr version 3.2.1 Index]