secr (version 3.0.1)

esa.plot:

Description

Plot effective sampling area (Borchers and Efford 2008) as a function of increasing buffer width.

Usage

esa.plot (object, max.buffer = NULL, spacing = NULL, max.mask = NULL,
    detectfn, detectpar, noccasions, binomN = NULL, thin = 0.1,
    poly = NULL, session = 1, plt = TRUE, as.density = TRUE, n = 1,
    add = FALSE, overlay = TRUE, ...)

Arguments

object

traps object or secr object output from secr.fit

max.buffer

maximum width of buffer in metres

spacing

distance between mask points

max.mask

mask 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

noccasions

number of sampling occasions

binomN

integer code for discrete distribution (see secr.fit)

thin

proportion of mask points to retain in plot and output

poly

matrix of two columns interpreted as the x and y coordinates of a bounding polygon (optional)

session

vector of session indices (used if object spans multiple sessions)

plt

logical to plot results

as.density

logical; if TRUE the y-axis is n / esa

n

integer number of distinct individuals detected

add

logical to add line to an existing plot

overlay

logical; if TRUE then automatically add = TRUE for plots after the first

…

graphical arguments passed to plot() and lines()

Value

A dataframe with columns

buffer

buffer width

esa

computed effective sampling area

density

n/esa

pdot

\(p.(\mathbf{X})\)

pdotmin

cumulative minimum (\(p.(\mathbf{X})\))

If plt = TRUE the dataframe is returned invisibly.

Details

Effective sampling area (esa) is defined as the integral of net capture probability (\(p.(\mathbf{X})\)) over a region. esa.plot shows the effect of increasing region size on the value of esa for fixed values of the detection parameters. The max.buffer or max.mask arguments establish the maximum extent of the region; points (cells) within this mask are sorted by their distance \(d_k\) from the nearest detector. esa(buffer) is defined as the cumulative sum of \(cp.(\mathbf{X})\) for \(d_k(\mathbf{X}) <= \mbox{buffer}\), where \(c\) is the area associated with each cell.

The default (as.density = TRUE) is to plot the reciprocal of esa multiplied by n; this is on a more familiar scale (the density scale) and hence is easier to interpret.

Because esa.plot uses the criterion `distance to nearest detector', max.mask should be constructed to include all habitable cells within the desired maximum buffer and no others. This is achieved with type = "trapbuffer" in make.mask. It is a good idea to set the spacing argument of make.mask rather than relying on the default based on nx. Spacing may be small (e.g. sigma/10) and the buffer of max.mask may be quite large (e.g. 10 sigma), as computation is fast.

Thinning serves to reduce redundancy in the plotted points, and (if the result is saved and printed) to generate more legible numerical output. Use thin=1 to include all points.

esa.plot calls the internal function esa.plot.secr when object is a fitted model. In this case detectfn, detectpar and noccasions are inferred from object.

References

Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture--recapture studies. Biometrics 64, 377--385.

See Also

mask, pdot, make.mask, mask.check, Detection functions

Examples

## with previously fitted model
esa.plot(secrdemo.0)

## from scratch
trps <- make.grid()
msk <- make.mask(trps, buffer = 200, spacing = 5, type = "trapbuffer")
detectpar <- list(g0 = 0.2, sigma = 25)
esa.plot(trps,,, msk, 0, detectpar, nocc = 10, col = "blue")
esa.plot(trps,,, msk, 0, detectpar, nocc = 5, col = "green",
    add = TRUE)

esa.plot(trps,,, msk, 0, detectpar, nocc = 5, thin = 0.002, plt = FALSE)