Spatially Explicit Capture–Recapture

Share:

Description

Estimate animal population density with data from an array of passive
detectors (traps) by fitting a spatial detection model by maximizing the
likelihood. Data must have been assembled as an object of class
capthist. Integration is by summation over the grid of points in
mask.

vector of initial values for beta parameters, or secr object from which they may be derived

link

list with optional components corresponding to ‘real’
parameters (e.g., ‘D’, ‘g0’, ‘sigma’), each a character string in
{"log", "logit", "identity", "sin"} for the link function of one real parameter

fixed

list with optional components corresponding to real parameters giving the scalar value to which the parameter is to be fixed

model

list with optional components each symbolically defining a linear predictor for one real parameter using formula notation

timecov

optional dataframe of values of time (occasion-specific) covariate(s).

sessioncov

optional dataframe of values of session-specific covariate(s).

hcov

character name of individual covariate for known
membership of mixture classes.

groups

optional vector of one or more variables with which to form groups. Each element should be the name of a factor variable in the covariates attribute of capthist.

dframe

optional data frame of design data for detection parameters

details

list of additional settings, mostly model-specific (see Details)

method

character string giving method for maximizing log likelihood

verify

logical, if TRUE the input data are checked with verify

biasLimit

numeric threshold for predicted relative bias due to
buffer being too small

trace

logical, if TRUE then output each evaluation of the likelihood, and other messages

ncores

integer number of cores to be used for parallel processing

...

other arguments passed to the maximization function

Details

secr.fit fits a SECR model by maximizing the likelihood. The
likelihood depends on the detector type ("multi", "proximity", "count",
"polygon" etc.) of the traps attribute of capthist
(Borchers and Efford 2008, Efford, Borchers and Byrom 2009, Efford,
Dawson and Borchers 2009, Efford 2011). The ‘multi’ form of the
likelihood is also used, with a warning, when detector type = "single"
(see Efford et al. 2009 for justification).

The default model is null (model = list(D~1, g0~1,
sigma~1) for detectfn = 'HN' and CL = FALSE), meaning
constant density and detection probability). The set of variables
available for use in linear predictors includes some that are
constructed automatically (t, T, b, B, bk, Bk, k, K), group (g), and
others that appear in the covariates of the input data. See also
usage for varying effort, timevaryingcov to
construct other time-varying detector covariates, and secr models
and secr-overview.pdf for more on
defining models.

buffer and mask are alternative ways to define the region
of integration (see mask). If mask is not specified then a
mask of type "trapbuffer" will be constructed automatically using the
specified buffer width in metres.

hcov is used to define a hybrid mixture model, used especially to
model sex differences (see hcov). (Allows some animals to
be of unknown class).

The length of timecov should equal the number of sampling
occasions (ncol(capthist)). Arguments timecov,
sessioncov and groups are used only when needed for terms
in one of the model specifications. Default link is list(D="log",
g0="logit", sigma="log").

If start is missing then autoini is used for D, g0
and sigma, and other beta parameters are set initially to arbitrary
values, mostly zero. start may be a previously fitted model. In
this case, a vector of starting beta values is constructed from the old
(usually nested) model and additional betas are set to zero. Mapping of
parameters follows the default in score.test, but user
intervention is not allowed. From 2.10.0 the new and old models need not
share all the same ‘real’ parameters, but any new real parameters, such
as ‘pmix’ for finite mixture models, receive a starting value of 0 on
the link scale (remembering e.g., invlogit(0) = 0.5 for parameter ‘pmix’).

binomN (previously a component of details) determines the
distribution that is fitted for the number of detections of an individual
at a particular detector, on a particular occasion, when the detectors
are of type ‘count’, ‘polygon’ or ‘transect’:

binomN > 1 binomial with size binomN

binomN = 1 binomial with size determined by usage

binomN = 0 Poisson

binomN < 0 negative binomial with size abs(binomN) – see
NegBinomial

The default with these detectors is to fit a Poisson distribution. The
‘size’ parameter of the negative binomial is not estimated: it must be
supplied. binomN should be an integer unless negative.

details is used for various specialized settings listed below. These are
described separately - see details.

autoini

session to use for starting values (default 1)

centred

centre x-y coordinates

chat

overdispersion of sighting counts Tu, Tm

chatonly

compute overdispersion for Tu and Tm, then exit

distribution

binomial vs Poisson N

fixedbeta

specify fixed beta parameter(s)

hessian

variance method

ignoreusage

override usage in traps object of capthist

intwidth2

controls optimise when only one parameter

knownmarks

known or unknown number of marked animals in sighting-only model

LLonly

compute one likelihood for values in start

miscparm

starting values for extra parameters fitted via userdist function

nsim

number of simulations to compute overdispersion

param

optional parameterisation code

telemetrytype

treat telemetry data as independent, dependent or concurrent

telemetrysigma

use coordinate information from telemetry

telemetrybvn

use bivariate normal prior for centres of telemetered animals

normalize

rescale detection to individual range use

usecov

spatial covariate of use for normalization

userdist

user-provided distance function or matrix

A mark-resight model is fitted if the markocc attribute of the capthist
‘traps’ object includes sighting occasions. See the vignette
secr-markresight.pdf
for a full account.

If method = "Newton-Raphson" then nlm is
used to maximize the log likelihood (minimize the negative log
likelihood); otherwise optim is used with the
chosen method ("BFGS", "Nelder-Mead", etc.). If maximization fails a
warning is given appropriate to the method.

From secr 2.5.1, method = "none" may be used to skip likelihood
maximization and compute only the hessian for the current dataset at the
values in start, and the corresponding variance-covariance matrix of
beta parameters. The computation uses fdHess from nlme.

If verify = TRUE then verify is called to check
capthist and mask; analysis is aborted if "errors" are found. Some
conditions that trigger an "error" are benign (e.g., no detections in
some sessions of a multi-session study of a sparse population); use
verify = FALSE to avoid the check. See also Note.

If buffer is used rather than mask, and biasLimit
is valid, then the estimated density is checked for bias due to the
choice of buffer. A warning is generated when buffer appears
to be too small (predicted RB(D-hat) > biasLimit, default 1%
relative bias). The prediction uses bias.D. No check
is performed when mask is specified, when biasLimit is 0,
negative or NA, or when the detector type is "polygon", "transect",
"polygonX" or "transectX".

If ncores > 1 the parallel package will be used to create
processes on multiple cores (see Parallel for more). Specifying
extra cores may improve the speed of multi-session analyses (it may also
slow them down, as data must be copied back and forth). There is
presently no benefit for single-session analyses.

Function par.secr.fit is an alternative and more effective
way to take advantage of multiple cores when fitting several models.

Value

The function secr.fit returns an object of class secr. This has
components

list with one component for each real parameter
(typically ‘D’, ‘g0’, ‘sigma’),giving the name of the link function
used for each real parameter.

fixed

saved input

parindx

list with one component for each real parameter giving
the indices of the ‘beta’ parameters associated with each real
parameter

model

saved input

details

saved input

vars

vector of unique variable names in model

betanames

names of beta parameters

realnames

names of fitted (real) parameters

fit

list describing the fit (output from nlm or
optim)

beta.vcv

variance-covariance matrix of beta parameters

smoothsetup

list of objects specifying smooths in mgcv

N

if CL = FALSE, array of predicted number in each group at
in each session, summed across mask, dim(N) = c(ngroups, nsessions),
otherwise NULL

version

secr version number

starttime

character string of date and time at start of fit

proctime

processor time for model fit, in seconds

Warning

** Mark-resight data formats and models are experimental in secr 2.10.0 and subject to change **

Note

One system of units is used throughout secr. Distances are in metres and
areas are in hectares (ha). The unit of density is animals per
hectare. 1 ha = 10000 m^2 = 0.01 km^2. To convert density to animals /
km^2, multiply by 100.

When you display an ‘secr’ object by typing its name at the command
prompt, you implicitly call its ‘print’ method print.secr, which
in turn calls predict.secr to tabulate estimates of the ‘real’
parameters. Confidence limits (lcl, ucl) are for a 100(1-alpha)%
interval, where alpha defaults to 0.05 (95% interval); alpha may be
varied in print.secr or predict.secr.

AIC, logLik and vcov methods are also
provided. Take care with using AIC: not all models are comparable (see
Notes section of AIC.secr) and large differences in AIC
may relate to trivial differences in estimated density.

derived is used to compute the derived parameters ‘esa’
(effective sampling area) and ‘D’ (density) for models fitted by
maximizing the conditional likelihood (CL = TRUE).

Components ‘version’ and ‘starttime’ were introduced in version 1.2.7,
and recording of the completion time in ‘fitted’ was discontinued.

The Newton-Raphson algorithm is fast, but it sometimes fails to compute
the information matrix correctly, causing some or all standard errors to
be set to NA. This usually indicates a major problem in fitting the
model, and parameter estimates should not be trusted. See
Troubleshooting.

The component D in output was replaced with N from version 2.3. Use
region.N to obtain SE or confidence intervals for N-hat,
or to infer N for a different region.

Prior to version 2.3.2 the buffer bias check could be switched off by
setting verify = FALSE. This is now done by setting
biasLimit = 0 or biasLimit = NA .