Description Usage Arguments Details Value The capt argument The ss.opts argument The optim.opts argument Fitted parameters Convergence Local integration References See Also Examples
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.
1 2 3 4 5 |
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. One of "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 |
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. |
phases |
A named list. Component names are parameter names, and each component is a phase for the associated parameter. See the section on convergence below for information on parameter phases. |
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.opts |
Options for models using the signal strength detection function. See 'Details' below. |
cue.rates |
A vector of call frequencies collected
independently of the main acoustic survey. This must be
measured in calls per unit time, where the time units are
equivalent to those used by |
survey.length |
The length of a cue-based survey. If provided,
the estimated density |
sound.speed |
The speed of sound in metres per second,
defaults to 330 (the speed of sound in air). Only used when
|
local |
Logical, if |
hess |
Logical, if |
trace |
Logical, if |
clean |
Logical, if |
optim.opts |
Optimisation options. See 'Details' for further information. |
... |
Other arguments (mostly for back-compatibility). |
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 cue.rates
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)
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.
capt
argumentThe 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.
ss.opts
argumentThis argument allows the user to select options for the signal
strength detection function (for more details, see the section
below on fitted parameters). It is therefore only required if
signal strength information appears in the capt
argument,
and is ignored (with a warning) otherwise.
The argument ss.opts
is a list with up to seven components:
cutoff
: Compulsory. The signal strength threshold,
above which sounds are identified as detections.
lower.cutoff
: Optional. Used for models where only
the first detected call is used in the capture history. The lower
cutoff is the signal strength value above which calls can be
assumed to have been detected with certainty.
het.source
: Optional. Logical, if TRUE
a model with
heterogeneity in source signal strengths is used. If unspecified,
it will default to FALSE
.
het.source.method
: Optional. A character string, either
"GH"
or "rect"
. If "GH", integration over source strengths
uses Gauss-Hermite quadrature. If "rect", the rectangle method is used.
n.het.source.quadpoints
: Optional. An integer, giving the number
of quadrature points used for numerical integration over source strengths.
Defaults to 15. A larger number of quadrature points leads to more accurate
results, but will increase computation time.
directional
: Optional. Logical, if TRUE
a
directional signal strength model is used; see the section below on
fitted parameters. If unspecified, it will default to FALSE
,
unless the b2.ss
parameter is provided in sv
or
fix
, in which case it will default to TRUE
.
n.dir.quadpoints
: Optional. An integer, giving the number of
quadrature points used for numerical integration over the possible
call directions. Defaults to 8, but needs to be larger when calls are
more directional (i.e., b2.ss parameter is large). A larger number of
quadrature points leads to more accurate results, but will increase computation
time.
ss.link
: Optional. A character string, either
"identity"
, "log"
, or "spherical"
, which
specifies the relationship between the expected received signal
strength and distance from the microphone. See details on the
signal strength detection function in the section 'Fitted
parameters' below. Defaults to "identity"
.
optim.opts
argumentThis argument allows the user to select options for the maximisation of the likelihood.
The argument optim.opts
is a list with up to four components:
cbs
: Optional. 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
: Optional. 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
: Optional. Character string, either
"old"
or "new"
, depending on which executable is to
be used (for development purposes only; please ignore).
neld.mead
: Optional. A logical value specifying
whether or not to use Nelder-Mead optimisation. Defaults to
FALSE
, which is recommended.
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"
in a non-directional model:
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
.
For detfn = "ss"
in a directional model:
Estimated paramters are b0.ss
, b1.ss
, b2.ss
and
sigma.ss
.
The expected signal strength is modelled differently depending on the value of ss.link
in ss.opts
:
For ss.link = "identity"
(the default):
E(SS) = h^{-1}( b0.ss - ( b1.ss - ( b2.ss * ( cos( theta ) - 1 ) ) ) * d
For ss.link = "log"
:
E(SS) = h^{-1}( b0.ss - ( b1.ss - ( b2.ss * ( cos( theta ) - 1 ) ) ) * d )
For ss.link = "spherical"
:
E(SS) = β_0 - 10 * \log_{10}(d^2) - ( b1.ss - ( b2.ss( \cos( θ ) - 1 ) ) ) * ( d - 1 )
In all cases theta is the difference between the bearing the animal is facing when it makes a call, and the bearing from the animal to the detector.
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.
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 tightening parameter bounds (as above), by setting parameter phases, or by setting appropriate scalefactors.
To improve convergence using parameter phases use the phases
argument. By default all parameters are given a phase of 1, unless
it is changed. First, all parameters with a phase of 1 will be
maximised over, while all others are fixed at their original
values. Following that, parameters with a phase of 2 are
introduced, with all parameters with later phases remaining
fixed. This process continues until all parameters are maximised
over. Maximising paramters in phases can greatly improve the
stability of optimisation.
To improve convergence using scalefactors, 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).
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.
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.
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.
1 2 3 4 5 6 7 8 9 10 11 | ## 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)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.