secr: trap.builder – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

trap.builder

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.

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)

## 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))

## Not run: 

## 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)
}
## GRTS as before, but excluding detectors from a polygon

if (requireNamespace('spsurvey')) {
  newgrid <- 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)
}

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

tempmask2 <- make.mask(minigrid, spacing = 10)
fit2 <- secr.fit(mash(tempcapt), mask = tempmask2, trace = FALSE)   ## 1.01 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)

secr

Spatially Explicit Capture-Recapture

v4.4.1

GPL (>= 2)

Authors

Murray Efford

Initial release

2021-05-01