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
.
1 2 3 4 5 6  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 =
"NewtonRaphson", verify = TRUE, biasLimit = 0.01, trace = NULL,
ncores = 1, ...)

capthist 

mask 

buffer 
scalar mask buffer radius if 
CL 
logical, if true then the model is fitted by maximizing the conditional likelihood 
detectfn 
integer code or character string for shape of detection function 0 = halfnormal, 1 = hazard rate etc. – see detectfn 
binomN 
integer code for distribution of counts (see Details) 
start 
vector of initial values for beta parameters, or 
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 
timecov 
optional dataframe of values of time (occasionspecific) covariate(s). 
sessioncov 
optional dataframe of values of sessionspecific 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 
dframe 
optional data frame of design data for detection parameters 
details 
list of additional settings, mostly modelspecific (see Details) 
method 
character string giving method for maximizing log likelihood 
verify 
logical, if TRUE the input data are checked with 
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 
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 timevarying detector covariates, and secr models
and secroverview.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 xy 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 sightingonly 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  userprovided distance function or matrix 
A markresight model is fitted if the markocc
attribute of the capthist
‘traps’ object includes sighting occasions. See the vignette
secrmarkresight.pdf
for a full account.
If method = "NewtonRaphson"
then nlm
is
used to maximize the log likelihood (minimize the negative log
likelihood); otherwise optim
is used with the
chosen method ("BFGS", "NelderMead", 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 variancecovariance 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 multisession 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(Dhat) > 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 multisession analyses (it may also
slow them down, as data must be copied back and forth). There is
presently no benefit for singlesession analyses.
Function par.secr.fit
is an alternative and more effective
way to take advantage of multiple cores when fitting several models.
The function secr.fit
returns an object of class secr. This has
components
call 
function call (as character string prior to secr 1.5) 
capthist 
saved input 
mask 
saved input 
detectfn 
saved input 
CL 
saved input 
timecov 
saved input 
sessioncov 
saved input 
hcov 
saved input (from 2.6.0) 
groups 
saved input 
dframe 
saved input 
design 
reduced design matrices, parameter table and parameter
index array for actual animals (see 
design0 
reduced design matrices, parameter table and parameter
index array for ‘naive’ animal (see 
start 
vector of starting values for beta parameters 
link 
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 
betanames 
names of beta parameters 
realnames 
names of fitted (real) parameters 
fit 
list describing the fit (output from 
beta.vcv 
variancecovariance 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 
** Markresight data formats and models are experimental in secr 2.10.0 and subject to change **
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(1alpha)%
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 NewtonRaphson 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 Nhat,
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
.
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 livetrapping 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: likelihoodbased 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
,
par.secr.fit
,
predict.secr
,
print.secr
,
region.N
,
Speed tips
Troubleshooting
userdist
usage
,
vcov.secr
,
verify
,
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24  ## Not run:
## construct test data (array of 48 `multicatch' 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 learnedresponse model for g0
secrb < secr.fit (detections, model = g0~b)
AIC (secr0, secrb)
## typical result
## model detectfn npar logLik AIC AICc dAICc 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
## End(Not run)

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
Please suggest features or report bugs with the GitHub issue tracker.
All documentation is copyright its authors; we didn't write any of that.