secr (version 1.3.0)

secr.fit: Spatially Explicit Capture--Recapture

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.

Usage

secr.fit (capthist, model = list(D~1, g0~1, sigma~1),
    mask = NULL, buffer = 100, CL = FALSE, detectfn = NULL,
    start = NULL, link = list(), fixed = list(),
    timecov = NULL, sessioncov = NULL, groups = NULL, dframe = NULL,
    details = list(), method = 'Newton-Raphson', verify = TRUE, trace = NULL, ...)

Arguments

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 etc.

start

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

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

trace

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

...

other arguments passed to the maximization function

Value

• 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

Details

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, 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. 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 nested model. In this case, a vector of starting beta values is constructed from the nested model and additional betas are set to zero. Mapping of parameters follows the default in score.test, but user intervention is not allowed. 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 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$scalesigma = TRUE causes sigma to be scaled by $\mathrm{D}^{-0.5}$. details$scaleg0 = TRUE causes g0 to be scaled by $\mathrm{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.

References

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.

See Also

capthist, mask, detection functions, print.secr, vcov.secr, AIC.secr, derived, predict.secr, verify

Examples

## 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 usually 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