esaPlot {secr}

R Documentation

Mask Buffer Diagnostic Plot

Description

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

esaPlot was previously called esa.plot.

Usage

esaPlot (object, max.buffer = NULL, spacing = NULL, max.mask = NULL,
    detectfn, detectpar, noccasions, binomN = NULL, thin = 0.1,
    poly = NULL, poly.habitat = TRUE, session = 1, plt = TRUE, 
    type = c('density', 'esa', 'meanpdot', 'CVpdot'), n = 1, add = FALSE, 
    overlay = TRUE, conditional = FALSE, ...)

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)
poly.habitat	logical as in make.mask
session	vector of session indices (used if object spans multiple sessions)
plt	logical to plot results
type	character, what to plot
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
conditional	logical; if TRUE the reported mean and CV are conditional on detection (see CVpdot)
...	graphical arguments passed to plot() and lines()

Details

Effective sampling area (esa) is defined as the integral of net capture probability (p.(\mathbf{X})) over a region. esaPlot 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 (type = 'density') 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 esaPlot 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.

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

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}))
meanpdot	expected pdot across mask (see CVpdot)
CVpdot	CV of pdot across mask (see CVpdot)

If plt = TRUE the dataframe is returned invisibly.

Note

The response of effective sampling area to buffer width is just one possible mask diagnostic; it's fast, graphic, and often sufficient. mask.check performs more intensive checks, usually for a smaller number of buffer widths.

The old argument 'as.density' was superceded by 'type' in 3.1.7.

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, CVpdot, make.mask, mask.check, Detection functions

Examples

## Not run: 

## with previously fitted model
esaPlot(secrdemo.0)

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

esaPlot(trps,,, msk, 0, detectpar, nocc = 5, thin = 0.002, plt = FALSE)


## End(Not run)

---