admbsecr: Fitting SECR models in ADMB

In admbsecr: SECR models with supplementary location information

Description

Fits an SECR model, with our without supplementary information relevant to animal location. Parameter estimation is done by maximum likelihood through an AD Model Builder (ADMB) executable.

Usage

admbsecr(capt, traps, mask, detfn = "hn", sv = NULL, bounds = NULL,
  fix = NULL, sf = NULL, ss.link = "identity", cutoff = NULL,
  call.freqs = NULL, sound.speed = 330, local = FALSE,
  hess = !any(call.freqs > 1), trace = FALSE, clean = TRUE, cbs = NULL,
  gbs = NULL, exe.type = "old")

Arguments

capt	A list with named components, containing the capture history and supplementary information. The function create.capt will return a suitable object. See 'Details' below.
traps	A matrix with two columns. Each row provides Cartesian coordinates for the location of a trap (or detector).
mask	A matrix with two columns. Each row provides Cartesian coordinates for the location of a mask point. The function create.mask will return a suitable object.
detfn	A character string specifying the detection function to be used. Options are "hn" (halfnormal), "hr" (hazard rate), "th" (threshold), "lth" (log-link threshold), or "ss" (signal strength). If the latter is used, signal strength information must be provided in capt.
sv	A named list. Component names are parameter names, and each component is a start value for the associated parameter. See 'Details' for further information on the parameters to be fitted.
bounds	A named list. Component names are parameter names, and each components is a vector of length two, specifying the bounds for the associated parameter.
fix	A named list. Component names are parameter names to be fixed, and each component is the fixed value for the associated parameter.
sf	A named list. Component names are parameter names, and each component is a scalefactor for the associated parameter. The default behaviour is to automatically select scalefactors based on parameter start values. See the section on convergence below.
ss.link	A character string, either "identity" or "log", which specifies the link function for the signal strength detection function. Only required when detfn is "ss" (i.e., when there is signal strength information in capt).
cutoff	The signal strength threshold, above which sounds are identified as detections. Only required when detfn is "ss".
call.freqs	A vector of call frequencies collected independently to an acoustic survey.
sound.speed	The speed of sound in metres per second, defaults to 330 (the speed of sound in air). Only used when "toa" is a component name of capt.
local	Logical, if TRUE integration over unobserved animal activity centres is only carried out in a region local to detectors that detected individuals. See 'Details'.
hess	Logical, if TRUE the Hessian is estimated, allowing for calculation of standard errors, the variance-covariance matrix, and the correlation matrix, at the expense of a little processing time. If FALSE, the Hessian is not estimated. Note that if individuals are detectable more than once (e.g., by calling more than once on an acoustic survey) then parameter uncertainty is not properly represented by these calculations.
trace	Logical, if TRUE parameter values at each step of the optimisation algorithm are printed to the R console.
clean	Logical, if TRUE ADMB output files are removed. Otherwise, ADMB output file will remain in a directory, the location of which is reported after the model is fitted.
cbs	The CMPDIF_BUFFER_SIZE, set using the -cbs option of the executable created by ADMB. This can be increased to speed up optimisation if cmpdiff.tmp gets too large (please ignore, unless you are familiar with ADMB and know what you are doing).
gbs	The GRADSTACK_BUFFER_SIZE, set using the -gbs option of the executable created by ADMB. This can be increased to speed up optimisation if gradfil1.tmp gets too large (please ignore, unless you are familiar with ADMB and know what you are doing).
exe.type	Character string, either "old" or "new", depending on which executable is to be used (for development purposes only; please ignore).

Details

ADMB uses a quasi-Newton method to find maximum likelihood estimates for the model parameters. Standard errors are calculated by taking the inverse of the negative of the Hessian. Alternatively, boot.admbsecr can be used to carry out a parametric bootstrap procedure, from which parameter uncertainty can also be inferred.

The class of model fitted by this function (and, indeed, around which this package is based) was first proposed by Borchers et al. (in press); this reference is a good starting point for practitioners looking to implement these methods.

If the data are from an acoustic survey where individuals call more than once (i.e., the argument call.freqs contains values that are not 1), then standard errors calculated from the inverse of the negative Hessian are not correct. They are therefore not provided in this case. The method used by the function boot.admbsecr is currently the only way to calculate these reliably (see Stevenson et al., in prep., for details).

Value

A list of class "admbsecr". Components contain information such as estimated parameters and standard errors. The best way to access such information, however, is through the variety of helper functions provided by the admbsecr package.

The capt argument

The capt argument is a list with named components. Each component must be an n by k matrix, where n is the number of detections made, and k is the number of traps (or detectors) deployed. A component named bincapt is compulsory.

Further optional component names each refer to a type of information which is informative on animal location collected on each detection. Possible choices are: bearing, dist, ss, toa, and mrds.

If the ith individual evaded the jth trap (or detector), then the jth element in the ith row should be 0 for all components. Otherwise, if the ith individual was trapped (or detected) by the jth trap (or detector), then:

• For the bincapt component, the element should be 1.

• For the bearing component, the element should be the estimated bearing from which the detector detected the individual.

• For the dist component, the element should be the estimated distance between the individual and the detector at the time of the detection.

• For the ss component, the element should be the measured signal strength of an acoustic signal detected by the detector (only possible when the detectors are microphones).

• For the toa component, the element should be the measured time of arrival (in seconds) since the start of the survey (or some other reference time) of an acoustic signal detected by the detector (only possible when the detectors are microphones).

• For the mrds component, the element should be the known (not estimated) distance between the individual and the detector at the time of the detection.

Fitted parameters

The parameter D, the density of individuals (or, in an acoustic survey, the density of calls) is always fitted. The effective survey area, esa, (see Borchers, 2012, for details) is always provided as a derived parameter, with a standard error calculated using the delta method.

Further parameters to be fitted depend on the choice of the detection function (i.e., the detfn argument), and the types of additional information collected (i.e., the components in the capt).

Details of the detection functions are as follows:

For detfn = "hn":

• Estimated paramters are g0 and sigma.

• g(d) = g0 * exp( -d^2 / (2 * sigma^2 ))

For detfn = "hr":

• Estimated parameters are g0, sigma, and z.

• g(d) = g0 * ( 1 - exp( -(d/sigma)^{-z} ) )

For detfn = "lth":

• Estimated parameters are shape.1 , shape.2 , and scale .

• g(d) = 0.5 - 0.5 * erf( shape.1 - exp( shape.2 - scale * d ) )

For detfn = "th":

• Estimated parameters are shape and scale .

• g(d) = 0.5 - 0.5 * erf( d/scale - shape )

For detfn = "ss":

• The signal strength detection function is special in that it requires signal strength information to be collected in order for all parameters to be estimated.

• Estimated parameters are b0.ss, b1.ss, and sigma.ss.

• The expected signal strength is modelled as: E(SS) = h^{-1}(b0.ss - b1.ss*d), where h is specified by the argument ss.link.

Details of the parameters associated with different additional data types are as follows:

For data type "bearing", kappa is estimated. This is the concerntration parameter of the von-Mises distribution used for measurement error in estimated bearings.

For data type "dist", alpha is estimated. This is the shape parameter of the gamma distribution used for measurement error in estimated distances.

For data type "toa", sigma.toa is estimated. This is the standard deviation parameter of the normal distribution used for measurement error in recorded times of arrival.

For data type "mrds", no extra parameters are estimated. Animal location is assumed to be known.

Convergence

If maximum likelihood estimates could not be found during optimisation, then admbsecr will usually show a warning that the maximum gradient component is large, or possibly throw an error reporting that a .par file is missing.

The best approach to fixing convergence issues is to re-run the admbsecr function with the argument trace set to TRUE. Parameter values will be printed out for each step of the optimisation algorithm.

First, look for a large jump in a parameter to a value far from what is feasible. This issue can be fixed by using the bounds argument to restrict the parameter space over which ADMB searches for the maximum likelihood estimate.

Alternatively, try a different set of start values using the argument sv; by default admbsecr will choose some start values, but these are not necessarily sensible. The start values that were used appear as the first line of text when trace is TRUE.

Sometimes the algorithm appears to converge, but nevertheless perseveres reporting the same parameter values again and again for a while (prior to the calculation of the Hessian). This is because ADMB has failed to detect convergence as at least one of the gradient components is still larger than the convergence criterion (by default, 0.0001). It is possible to speed things up and help ADMB detect convergence earlier by either tightening parameter bounds (as above), or by setting appropriate scalefactors (using the argument sf). To do this, first identify which parameters have large gradient components from the "final statistics" section of the trace output. Next, find the default settings of the scalefactors by printing the object fit$args$sf, where fit is the original object returned by admbsecr. Finally, rerun admbsecr again, but this time set the argument sf manually. Set scalefactors for any parameters with small gradient components to the same as the defaults ascertained above, and increase those associated with large gradient components by a factor of 10. If the problem persists, repeat this process (e.g., if the same parameters still have large gradient components, increase the associated scalefactors by another factor of 10).

Local integration

For SECR models, the likelihood is calculated by integrating over the unobserved animal activity centres (see Borchers & Efford, 2008). Here, the integral is approximated numerically by taking a finite sum over the mask points. The integrand is negligible in size for mask points far from detectors that detected a particular individual, and so to increase computational efficiency the region over which this sum takes place can be reduced.

Setting local to TRUE will only carry out this sum across mask points that are within the mask buffer distance of all detectors that made a detection. So long as the buffer suitably represents a distance beyond which detection is practically impossible, the effect this has on parameter estimates is negligible, but processing time can be substantially reduced.

Note that this increases the parameter estimates' sensitivity to the buffer. A buffer that is too small will lead to inaccurate results.

References

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

Borchers, D. L. (2012) A non-technical overview of spatially explicit capture-recapture models. Journal of Ornithology, 152: 435–444.

Borchers, D. L., Stevenson, B. C., Kidney, D., Thomas, L., and Marques, T. A. (in press) A unifying model for capture-recapture and distance sampling surveys of wildlife populations. Journal of the American Statistical Association.

Stevenson, B. C., Borchers, D. L., Altwegg, R., Swift, R. J., Gillespie, D. M., and Measey, G. J. (submitted) A general framework for animal density estimation from acoustic detections across a fixed microphone array.

See Also

boot.admbsecr to calculate standard errors and estimate bias using a parametric bootstrap.

coef.admbsecr, stdEr.admbsecr, and vcov.admbsecr to extract estimated parameters, standard errors, and the variance-covariance matrix, respectively.

confint.admbsecr to calculate confidence intervals.

summary.admbsecr to get a summary of estimates and standard errors.

show.detfn to plot the estimated detection function.

locations to plot estimated locations of particular individuals or calls.

Examples

## Not run: 
simple.capt <- example$capt["bincapt"]
simple.hn.fit <- admbsecr(capt = simple.capt, traps = example$traps,
                          mask = example$mask, fix = list(g0 = 1))
simple.hr.fit <- admbsecr(capt = simple.capt, traps = example$traps,
                          mask = example$mask, detfn = "hr")
bearing.capt <- example.capt[c("bincapt", "bearing")]
bearing.hn.fit <- admbsecr(capt = bearing.capt, traps = example$traps,
                           mask = example$mask, fix = list(g0 = 1))

## End(Not run)

admbsecr documentation built on May 2, 2019, 5:21 p.m.