suggest.buffer: Mask Buffer Width

Description

Determines a suitable buffer width for an integration mask. The `buffer' in question defines a concave polygon around a detector array constructed using make.mask with type = "trapbuffer". The method relies on an approximation to the bias of maximum likelihood density estimates (M. Efford unpubl).

Usage

suggest.buffer(object, detectfn = NULL, detectpar = NULL, 
    noccasions = NULL, ignoreusage = FALSE, ncores = NULL, RBtarget = 0.001,
    interval = NULL, binomN = NULL, ...)
bias.D (buffer, traps, detectfn, detectpar, noccasions, binomN = NULL,
    control = NULL)

Value

suggest.buffer returns a scalar value for the suggested buffer width in metres, or a vector of such values in the case of a multi-session object.

bias.D returns a dataframe with columns buffer and RB.D

(approximate bias of density estimate using finite buffer width, relative to estimate with infinite buffer).

Arguments

object: single-session `secr', `traps' or `capthist' object
detectfn: integer code or character string for shape of detection function 0 = halfnormal etc. -- see detectfn
detectpar: list of values for named parameters of detection function -- see detectpar
noccasions: number of sampling occasions
ignoreusage: logical for whether to discard usage information from traps(capthist)
ncores: integer number of threads to use for parallel processing
RBtarget: numeric target for relative bias of density estimate
interval: a vector containing the end-points of the interval to be searched
binomN: integer code for distribution of counts (see secr.fit)
...: other argument(s) passed to bias.D
buffer: vector of buffer widths
traps: `traps' object
control: list of mostly obscure numerical settings (see Details)

Details

The basic input style of suggest.buffer uses a `traps' object and a detection model specified by `detectpar', `detectfn' and `noccasions', plus a target relative bias (RB). A numerical search is conducted for the buffer width that is predicted to deliver the requested RB. If interval is omitted it defaults to (1, 100S) where S is the spatial scale of the detection function (usually detectpar$sigma). An error is reported if the required buffer width is not within interval. This often happens with heavy-tailed detection functions (e.g., hazard-rate): choose another function, a larger RBtarget or a wider interval.

Setting ncores = NULL uses the existing value from the environment variable RCPP_PARALLEL_NUM_THREADS (see setNumThreads).

Convenient alternative input styles are --

secr object containing a fitted model. Values of `traps', `detectpar', `detectfn' and `noccasions' are extracted from object and any values supplied for these arguments are ignored.
capthist object containing raw data. If detectpar is not supplied then autoini is used to get `quick and dirty' values of g0 and sigma for a halfnormal detection function. noccasions is ignored. autoini tends to underestimate sigma, and the resulting buffer also tends to be too small.

bias.D is called internally by suggest.buffer.

Examples

Run this code


if (FALSE) {

temptraps <- make.grid()
detpar <-  list(g0 = 0.2, sigma = 25)
suggest.buffer(temptraps, "halfnormal", detpar, 5)

suggest.buffer(secrdemo.0)

suggest.buffer(ovenCH[[1]])

RB <- bias.D(50:150, temptraps, "halfnormal", detpar, 5)
plot(RB)

detpar <-  list(g0 = 0.2, sigma = 25, z=5)
RB <- bias.D(50:150, temptraps, "hazard rate", detpar, 5)
lines(RB)

## compare to esa plot
esa.plot (temptraps, max.buffer = 150, spacing = 4, detectfn = 0,
  detectpar = detpar, noccasions = 5, type = "density")

## compare detection histories and fitted model as input
suggest.buffer(captdata)
suggest.buffer(secrdemo.0)

}