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.
secr.fit (capthist, model = list(D~1, g0~1, sigma~1), mask = NULL, buffer = NULL,
CL = FALSE, detectfn = NULL, binomN = NULL, start = NULL, link = list(),
fixed = list(), timecov = NULL, sessioncov = NULL, hcov = NULL,
groups = NULL, dframe = NULL, details = list(), method =
"Newton-Raphson", verify = TRUE, biasLimit = 0.01, trace = NULL,
ncores = NULL, ...)
When details$LLonly = TRUE a single log-likelihood is returned, with attributes
number of parameters to be estimated,
elapsed setup time in seconds,
elapsed time for single likelihood evaluation, exclusive of setup.
Otherwise, secr.fit returns an object of class secr representing the fitted SECR model. This has
components
function call)
saved input
saved input
saved input
saved input
saved input
saved input
saved input
saved input
saved input
design matrix for density model; may be NULL
design matrix for noneuc model; may be NULL
reduced design matrices for detection parameters, parameter table and parameter
index array for actual animals (see secr.design.MS)
reduced design matrices for detection parameters, parameter table and parameter
index array for `naive' animal (see secr.design.MS)
vector of starting values for beta parameters
list with one component for each real parameter (typically `D', `g0', `sigma'),giving the name of the link function used for each real parameter.
saved input
list with one component for each real parameter giving the indices of the `beta' parameters associated with each real parameter
saved input
saved input
vector of unique variable names in model
names of beta parameters
names of fitted (real) parameters
list describing the fit (output from nlm or
optim)
variance-covariance matrix of beta parameters
list of objects specifying smooths in mgcv
logical; TRUE if any learned response in detection model
secr version number
character string of date and time at start of fit
processor time for model fit, in seconds
The environment variable RCPP_PARALLEL_NUM_THREADS is updated if an integer value is provided for ncores.
capthist object including capture data and detector (trap) layout
mask object or (for a multi-session analysis) a list of mask objects, one for each session
scalar mask buffer radius if mask not specified
(default 100 m)
logical, if true then the model is fitted by maximizing the conditional likelihood
integer code or character string for shape of detection function 0 = halfnormal, 1 = hazard rate etc. -- see detectfn
integer code for distribution of counts (see Details)
vector of initial values for beta parameters, or secr object from which they may be derived
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
list with optional components corresponding to real parameters giving the scalar value to which the parameter is to be fixed
list with optional components each symbolically defining a linear predictor for one real parameter using formula notation
optional dataframe of values of time (occasion-specific) covariate(s).
optional dataframe of values of session-specific covariate(s).
character name of individual covariate for known membership of mixture classes.
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.
optional data frame of design data for detection parameters
list of additional settings, mostly model-specific (see Details)
character string giving method for maximizing log likelihood
logical, if TRUE the input data are checked with verify
numeric threshold for predicted relative bias due to buffer being too small
logical, if TRUE then output each evaluation of the likelihood, and other messages
integer number of threads to use for parallel processing
other arguments passed to the maximization function
** Mark-resight data formats and models are experimental in secr 2.10.0 and subject to change **
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.pdf
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
The default with these detectors is to fit a Poisson distribution.
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 |
| contrasts | coding of factor predictors |
| convexpolygon | allows non-convex polygons (slower) |
| Dfn | reparameterization of density model (seldom used directly) |
| Dlambda | switch density reparameterization to trend model |
| distribution | binomial vs Poisson N |
| fastproximity | special handling of binary proximity detectors |
| fixedbeta | specify fixed beta parameter(s) |
| grain | grain argument of RcppParallel::parallelFor |
| 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 |
| maxdistance | distance threshold for selective mask |
| miscparm | starting values for extra parameters fitted via userdist function |
| newdetector | detector type to override detector(traps(capthist)) |
| nsim | number of simulations to compute overdispersion |
| param | optional parameterisation code |
| relativeD | optional relative density conditional on \(n\) |
| savecall | optionally suppress saving of call |
| telemetrytype | treat telemetry data as independent, dependent or concurrent |
| normalize | rescale detection to individual range use |
| usecov | spatial covariate of use for normalization |
| userdist | user-provided distance function or matrix |
Setting ncores = NULL uses the existing value from the environment variable
RCPP_PARALLEL_NUM_THREADS (see setNumThreads).
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".
Function list.secr.fit is a way to fit several models at once.
Borchers, D. L. and Efford, M. G. (2008) Spatially explicit maximum likelihood methods for capture--recapture studies. Biometrics 64, 377--385.
Efford, M. G. (2004) Density estimation in live-trapping studies. Oikos 106, 598--610.
Efford, M. G. (2011) Estimation of population density by spatially explicit capture--recapture with area searches. Ecology 92, 2202--2207.
Efford, M. G., Borchers D. L. and Byrom, A. E. (2009) Density estimation by spatially explicit capture--recapture: likelihood-based methods. In: D. L. Thompson, E. G. Cooch and M. J. Conroy (eds) Modeling Demographic Processes in Marked Populations. Springer. Pp. 255--269.
Efford, M. G., Dawson, D. K. and Borchers, D. L. (2009) Population density estimated from locations of individuals on a passive detector array. Ecology 90, 2676--2682.
Detection functions,
AIC.secr,
capthist,
details,
derived,
hcov,
mask,
list.secr.fit,
predict.secr,
print.secr,
region.N,
Speed tips
Troubleshooting
userdist
usage,
vcov.secr,
verify,
if (FALSE) {
## construct test data (array of 48 `multi-catch' traps)
detectors <- make.grid (nx = 6, ny = 8, detector = "multi")
detections <- sim.capthist (detectors, popn = list(D = 10,
buffer = 100), detectpar = list(g0 = 0.2, sigma = 25))
## fit & print null (constant parameter) model
secr0 <- secr.fit (detections)
secr0 ## uses print method for secr
## compare fit of null model with learned-response model for g0
secrb <- secr.fit (detections, model = g0~b)
AIC (secr0, secrb)
## typical result
## model detectfn npar logLik AIC AICc dAIC AICwt
## secr0 D~1 g0~1 sigma~1 halfnormal 3 -347.1210 700.242 700.928 0.000 0.7733
## secrb D~1 g0~b sigma~1 halfnormal 4 -347.1026 702.205 703.382 2.454 0.2267
}
Run the code above in your browser using DataLab