optimalSpacing {secrdesign}

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)