suggest.buffer {secr}

R Documentation

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)

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.

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

Note

The algorithm in bias.D uses one-dimensional numerical integration of a polar approximation to site-specific detection probability. This uses a further 3-part linear approximation for the length of contours of distance-to-nearest-detector (r) as a function of r.

The approximation seems to work well for a compact detector array, but it should not be taken as an estimate of the bias for any other purpose: do not report RB.D as "the relative bias of the density estimate". RB.D addresses only the effect of using a finite buffer. The effect of buffer width on final estimates should be checked with mask.check.

The default buffer type in make.mask, and hence in secr.fit, is ‘traprect’, not ‘trapbuffer’, but a buffer width that is adequate for ‘trapbuffer’ is always adequate for ‘traprect’.

control contains various settings of little interest to the user.

The potential components of control are –

method = 1

code for method of modelling p.(X) as a function of buffer (q(r))

bfactor = 20

q(r) vs p.(X) calibration mask buffer width in multiples of trap spacing

masksample = 1000

maximum number of points sampled from calibration mask

spline.df = 10

effective degrees of freedom for smooth.spline

ncores = NULL

integer number of cores

See Also

mask, make.mask, mask.check, esaPlot

Examples

## Not run: 

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
esaPlot (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)


## End(Not run)

---