details: Detail Specification for secr.fit
Description
The function secr.fit allows many options. Some of these are used
infrequently and have been bundled as a single argument details
to simplify the documentation. They are described here.Detail components
details$centred = TRUE causes coordinates of both traps and mask
to be centred on the centroid of the traps, computed separately for each
session in the case of multi-session data. This may be necessary to
overcome numerical problems when x- or y-coordinates are large
numbers. The default is not to centre coordinates.
details$distribution specifies the distribution of the number of
individuals detected $n$; this may be conditional on the number in the
masked area ("binomial") or unconditional ("poisson").
distribution affects the sampling variance of the estimated
density. The default is "poisson". The component `distribution' may also
take a numeric value larger than nrow(capthist), rather than "binomial"
or "poisson". The likelihood then treats n as a binomial draw from a
superpopulation of this size, with consequences for the variance of
density estimates. This can help to reconcile MLE with Bayesian
estimates using data augmentation.
details$fixedbeta may be used to fix values of beta
parameters. It should be a numeric vector of length equal to the total
number of beta parameters (coefficients) in the model. Parameters to be
estimated are indicated by NA. Other elements should be valid values on
the link scale and will be substituted during likelihood
maximisation. Check the order of beta parameters in a previously fitted
model.
details$hessian is a character string controlling the computation
of the Hessian matrix from which variances and covariances are obtained.
Options are "none" (no variances), "auto" (the default) or "fdhess" (use
the function fdHess in nlme). If "auto" then the Hessian from the
optimisation function is used. See also method = "none" below.
details$ignoreusage = TRUE causes the function to ignore
usage (varying effort) information in the traps component. The default
(details$ignoreusage = FALSE) is to include usage in the model.
details$intwidth2 controls the half-width of the interval
searched by optimise() for the maximum likelihood when there is a single
parameter. Default 0.8 sets the search interval to $(0.2s, 1.8s)$ where $s$
is the `start' value.
details$LLonly = TRUE causes the function to returns a single
evaluation of the log likelihood at the `start' values.
details$param chooses between various parameterisations of the
SECR model. The default details$param = 0 is the formulation in
Borchers and Efford (2008) and later papers.
details$param = 1 selects the Gardner & Royle parameterisation of
the detection model (p0, $\sigma$; Gardner et al. 2009) when
the detector type is `multi'. This parameterisation does not allow
detector covariates.
details$param = 2 selects parameterisation in terms of
($esa(g_0, \sigma)$, $\sigma$) (Efford and Mowat 2014).
details$param = 3 selects parameterisation in terms of
($a_0(lambda0, \sigma)$, $\sigma$) (Efford and Mowat 2014). This
parameterization is used automatically if a0 appears in the model (e.g.,
a0 ~ 1).
details$param = 4 selects parameterisation of sigma in terms of
the coefficient sigmak and constant c (sigma = sigmak /
D^0.5 + c) (Efford et al. in prep). If c is not included explicitly in
the model (e.g., c ~ 1) then it is set to zero. This
parameterization is used automatically if sigmak appears in the model (e.g.,
sigmak ~ 1)
details$param = 5 combines parameterisations (3) and (4) (first
compute sigma from D, then compute lambda0 from sigma).
details$scaleg0 = TRUE causes g0 to be scaled by
$\mathrm{sigma}^{-2}$. Deprecated from 2.6.2: use a0
parameterisation instead.
details$scalesigma = TRUE causes sigma to be scaled by
$\mathrm{D}^{-0.5}$. Deprecated from 2.7.1: use sigmak
parameterisation instead.
details$telemetrytype determines how telemetry data in the
attribute `xylist' are treated. `none' causes the xylist data to be
ignored. `dependent' uses information on the sampling distribution of
each home-range centre in the SECR likelihood. `concurrent' does that
and more: it splits capthist according to telemetry status and appends
all-zero histories to the telemetry part for any animals present in
xylist. The default is `concurrent'.
details$telemetrysigma = TRUE uses coordinate information from
telemetry for estimating spatial detection parameters when capthist has
attribute `xylist' (see addTelemetry). The default is
FALSE. details$telemetrysigma is always TRUE when
details$telemetrytype = 'independent'.
details$telemetrybvn = TRUE includes a bivariate normal prior for
the centres of telemetered individuals when details$telemetrytype
is `concurrent' or `dependent'; otherwise the sample mean of telemetry
locations is taken as the known location (without uncertainty). The
default is FALSE.
details$normalize = TRUE rescales detection so that individual range use
sums to 1.0 (cf Royle et al. 2013)
details$usecov selects the mask covariate to be used for
normalization. NULL limits denominator for normalization to
distinguishing habitat from non-habitat.
details$userdist is either a function to compute non-Euclidean
distances between detectors and mask points, or a pre-computed matrix of
such distances. The first two arguments of the function should be
2-column matrices of x-y coordinates (respectively $k$ detectors and
$m$ mask points). The third argument, if present, defines a
non-Euclidean habitat geometry (a linear geometry is described in
documentation for the forthcoming package `secrlinear'). The fourth
argument, if present, is a parameter of the distance algorithm. The
matrix returned by the function must have exactly $k$ rows and
$m$ columns. Full documentation will follow in a later release.
**Do not use `userdist' for polygon or transect detectors**References
Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity in
capture--recapture data.Ecology 95, 1341--1348.
Gardner, B., Royle, J. A. and Wegan, M. T. (2009) Hierarchical models
for estimating density from DNA mark-recapture studies. Ecology
90, 1106--1115.
Royle, J. A., Chandler, R. B., Sun, C. C. and Fuller, A. K. (2013)
Integrating resource selection information with spatial
capture--recapture. Methods in Ecology and Evolution 4, 520--530.