# Complex Detector Layouts

### Description

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

### Usage

1 2 3 4 5 6 7 8 9 10 11 | ```
trap.builder (n = 10, cluster, region = NULL, frame = NULL, method =
c("SRS", "GRTS", "all", "rank"), edgemethod = c("clip", "allowoverlap",
"allinside"), samplefactor = 2, ranks = NULL, rotation = NULL, detector,
exclude = NULL, exclmethod = c("clip", "alloutside"), 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 |

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

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

`edgemethod`

may be "clip" (reject individual detectors),
"allowoverlap" (no action) or "allinside" (reject whole cluster if any
component is outside `region`

). Similarly, `exclmethod`

may
be "clip" (reject individual detectors) or "alloutside" (reject whole cluster if any
component is outside `exclude`

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | ```
## 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 (require(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 (require(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)
``` |