| secr.fit {secr} | R Documentation |
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 = 100, CL = FALSE, detectfn = 0,
start = NULL, link = list(), fixed = list(),
timecov = NULL, sessioncov = NULL, groups = NULL, dframe = NULL,
details = list(), method = 'Newton-Raphson', verify = TRUE, ...)
capthist |
capthist object including capture data and detector (trap) layout |
mask |
mask object |
buffer |
scalar mask buffer radius if mask not specified |
CL |
logical, if true then the model is fitted by maximizing the conditional likelihood |
detectfn |
integer code for shape of detection function. 0 halfnormal, 1 hazard-rate, 2 exponential |
start |
vector of initial values for beta parameters |
link |
list with optional components 'D', 'g0', 'sigma' and 'z', each a character string in {'log', 'logit', 'identity', 'sin'} for the link function of the relevant real parameter |
fixed |
list with optional components corresponding to each 'real' parameter (e.g., 'D', 'g0', 'sigma'), the scalar value to which parameter is to be fixed |
model |
list with optional components 'D', 'g0', 'sigma' and 'z', each symbolically defining a linear predictor for the relevant 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). |
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 |
... |
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' or 'proximity') of the
'traps' attribute of capthist (Borchers and Efford 2008,
Efford, Borchers and Byrom 2009, Efford, Dawson and Borchers 2009). The
'multi' form of the likelihood is also used, with a warning, when
detector type = 'single' (see Efford et al. 2009). Default model
is null (constant density and detection probability). The set of
variables available for use in linear predictors includes some that are
constructed automatically (t, b, B), group (g), and others that appear
in the covariates of the input data. See secr models for
more on defining models.
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. If start
is missing then autoini is used for D, g0 and sigma; other
beta parameters are set initially to zero. Default link is
list(D='log', g0='logit', sigma='log', z='log').
details is used for various specialized settings –
details$distribution specifies the distribution of the number of
individuals detected; this may be conditional on the number in the
masked area ('binomial') or unconditional ('poisson').
distribution affects only the sampling variance of the estimated
density. The default is 'poisson'.
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.
details$LLonly = TRUE causes the function to returns a single
evaluation of the log likelihood at the 'start' values.
details$trace = TRUE displays a one-line summary at each
evaluation of the likelihood, and other messages.
details$scalesigma = TRUE causes sigma to be scaled by
1/sqrt(D).
details$scaleg0 = TRUE causes g0 to be scaled by
sigma^-2. The corresponding 'real' parameters
are marked with an asterisk in output (e.g. g0*).
If method = 'Newton-Raphson' then nlm is
used to maximize the log likelihood; otherwise
optim is used with the chosen method
('BFGS','Nelder-Mead', etc.). A feature of nlm is that it takes a
large step early on in the maximization that may cause floating point
underflow or overflow in one or more real parameters. This can be
controlled by passing the 'stepmax' argument of nlm in the ...
argument of secr.fit (see first example).
If verify = TRUE then verify is called to check
capthist and mask; analysis is aborted if errors are found.
The function secr.fit returns an object of class secr. This has components
call |
function call |
capthist |
saved input |
mask |
saved input |
detectfn |
saved input |
CL |
saved input |
timecov |
saved input |
sessioncov |
saved input |
groups |
saved input |
dframe |
saved input |
design |
reduced design matrices, parameter table and parameter index array for actual animals (see secr.design.MS) |
design0 |
reduced design matrices, parameter table and parameter index array for 'naive' animal (see secr.design.MS) |
start |
vector of starting values for beta parameters |
link |
list with components for each real parameter (e.g., 'D', 'g0'), the name of the link function used for each real parameter. Component 'z' is NULL unless detectfn = 1 (hazard-rate). |
fixed |
saved input |
parindx |
list with possible components 'D', 'g0', 'sigma' and 'z', for the indices of the 'beta' parameters associated with each real parameter ('z' NULL unless detectfn = 1). |
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 |
D |
array of predicted densities of each group at each mask point in each session, dim(D) = c(nrow(mask), ngroups, nsessions) |
version |
secr version number |
starttime |
character string of date and time at start of fit |
proctime |
processor time for model fit, in seconds |
print, AIC, vcov, and predict methods
are provided. 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.
Murray Efford murray.efford@otago.ac.nz
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., 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.
capthist, mask, detection functions,
print.secr, vcov.secr, AIC.secr,
derived, predict.secr, verify
## 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
## stepmax is passed to nlm (not needed)
secr0 <- secr.fit (detections, stepmax = 50)
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 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