optimalSpacing: Optimal Detector Spacing

In secrdesign: Sampling Design for Spatially Explicit Capture-Recapture

Optimal Detector Spacing

Description

Estimate the detector spacing that yields the greatest precision for a given detector geometry, number of sampling occasions, density and detection parameters.

Usage

optimalSpacing (D, traps, detectpar, noccasions, nrepeats = 1, 
    detectfn = c('HHN', 'HHR', 'HEX','HAN','HCG', 'HN', 'HR', 'EX'),
    fittedmodel = NULL, xsigma = 4, R = seq(0.2, 4, 0.2), CF = 1.0,
    distribution = c("poisson", "binomial"),
    fit.function = c("none", "secr.fit"), 
    simulationR = seq(0.4, 4, 0.4), nrepl = 10, 
    plt = FALSE, ...) 

Arguments

D	population density animals / hectare (constant)
traps	traps object
detectpar	named list giving a value for each parameter of detection function (sigma not needed)
noccasions	integer number of sampling occasions
nrepeats	integer number of replicate arrays (not yet used)
detectfn	integer code or character string for shape of detection function – see detectfn
fittedmodel	secr fitted model (instead of preceding arguments)
xsigma	numeric buffer width as multiple of sigma
R	numeric vector of relative spacings at which to plot rule-of-thumb RSE(D-hat)
CF	numeric correction factor for rule-of-thumb RSE
distribution	character distribution of number of individuals detected
fit.function	character function to use for model fitting
simulationR	numeric vector of relative spacings at which to simulate
nrepl	integer number of replicate simulations
plt	logical; if TRUE then results are plotted
...	other arguments passed to various functions (see Details)

Details

A numerical search over possible spacings uses the rule-of-thumb RSE(D-hat) given by minnrRSE as the objective function.

traps provides the geometry of the detector layout and the initial spacing s. Function optimize is used to search for a solution (minimum RSE) in the range of R x s.

The computation emulates variation in detector spacing by inverse variation in sigma (sigma' = sigma / R) with compensating variation in density. Mask buffer width and spacing are also scaled by R.

If fit.function is not "none" then simulations are also performed for the relative spacings in simulationR. Density, sigma and mask attributes are scaled as for the rule-of-thumb calculations. Using 'method = "none"' gives fast prediction of RSE (from the Hessian evaluated at the known parameter values), but does not estimate bias.

The ... argument may be used to set the values of these arguments:

Function	Arguments
make.mask	`nx', `type', `poly',`poly.habitat'
run.scenarios	`seed', `ncores', `method'
plot.optimalSpacing	`add', ...

The argument CF may be set to NA to suppress rule-of-thumb RSE, including optimisation. range(R) specifies the search interval for optimisation.

A plot method is provided, with options for plotting different components.

Value

List of two components, one for the rule-of-thumb optimisation (rotRSE) and the other for simulation results, if requested (simRSE).

The optimisation results are

values	dataframe with E(n), E(r) and the rule-of-thumb RSE for each requested R
optimum.spacing	the absolute spacing that yields maximum precision (minimum rule-of-thumb RSE(D-hat))
optimum.R	spacing relative to sigma
minimum.RSE	final value of the objective function (minimum rule-of-thumb RSE(D-hat))

The simulation results in the dataframe simRSE are the mean and SE of the simulated RSE(D-hat) for each level of simulationR, with added columns for the relative bias (RB) and relative root-mean-square-error (rRMSE) of D-hat.

Results are returned invisibly if plt = TRUE.

Warnings

For single-catch traps, use of a maximum likelihood estimate of lambda0 from a fitted multi-catch model results in negative bias.

Only hazard-based detection functions are supported. The meaning of the ‘sigma’ parameter depends on the function, and so will the optimal spacing in sigma units.

Note

fit.function = 'openCR.fit' was deprecated from 2.5.8 and has been removed as an option

See Also

minnrRSE, plot.optimalSpacing

Examples

grid <- make.grid(7, 7)  # default multi-catch detector
optimalSpacing(D = 5, traps = grid, detectpar = list(lambda0 = 0.2, sigma = 20), 
   noccasions = 5, plt = TRUE)

## Not run: 

optimalSpacing(D = 5, traps = grid, detectpar = list(lambda0 = 0.4, sigma = 20), 
    detectfn = 'HEX', R = seq(1,6,0.4), noccasions = 10, plt = TRUE, col = "blue")

## with simulations
grid <- make.grid(8, 8, spacing = 20, detector = 'proximity')
optimalSpacing(D = 5, traps = grid, detectfn = "HHN", detectpar = 
    list(lambda0 = 0.2, sigma = 20), noccasions = 5, nrepl = 20, nx = 32, 
    ncores = 4, plt = TRUE, col = "blue")

## manual check
grid <- make.grid(8, 8, spacing = 60, detector = 'proximity')
scen <- make.scenarios(D = 5, detectfn = 14, lambda0 = 0.2, sigma = 20,
    noccasions = 5)
sim1 <- run.scenarios(nrepl = 20, scen, trapset = list(grid), fit = TRUE, 
    fit.args = list(detectfn = 14), ncores = 4, byscenario = FALSE)
summary(sim1)


## End(Not run)

secrdesign documentation built on March 31, 2023, 10:25 p.m.