secr (version 2.5.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 = NULL, CL = FALSE, detectfn = NULL,
    binomN = NULL, start = NULL, link = list(), fixed = list(),
    timecov = NULL, sessioncov = NULL, groups = NULL,
    dframe = NULL, details = list(), method = "Newton-Raphson",
    verify = TRUE, biasLimit = 0.01, trace = NULL, ncores = 1, ...)

Arguments

capthist

capthist object including capture data and detector (trap) layout

mask

mask object

buffer

scalar mask buffer radius if mask not specified (default 100 m)

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

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 available for parallel processing

...

other arguments passed to the maximization function

Value

• 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
• 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 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
• 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

code

ncores > 1

pkg

• nlme
• parallel

eqn

$\sigma$

emph

p0

link

Parallel

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 (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 ../doc/secr-overview.pdf for more on defining models. buffer and mask are alternative ways to define the region of integration (see mask). 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. 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 dnbinom}

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. (2011) Estimation of population density by spatially explicit capture--recapture with area or transect searches. Unpublished manuscript. 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. Gardner, B., Royle, J. A. and Wegan, M. T. (2009) Hierarchical models for estimating density from DNA mark-recapture studies. Ecology 90, 1106--1115.

See Also

detection functions, AIC.secr, capthist, derived, mask, predict.secr, print.secr, region.N, troubleshooting usage, vcov.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
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 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