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

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`

### See Also

`mask`, `make.mask`, `mask.check`, `esa.plot`

### Examples

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

    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, as.density = F)

    ## End(Not run)

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

[Package secr version 3.2.1 Index]