secr.fit {secr} | R Documentation

## 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 = 0,
        start = NULL, link = list(), fixed = list(),
        timecov = NULL, sessioncov = NULL, groups = NULL, dframe = NULL,
        details = list(), method = 'Newton-Raphson', verify = TRUE, ...)

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

### 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, 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, and other beta parameters are set initially to arbitrary values, mostly zero. Default `link` is list(D='log', g0='logit', sigma='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 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.

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

### Note

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

### Author(s)

Murray Efford murray.efford@otago.ac.nz

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

[Package secr version 1.3.0 Index]