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 = 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 =
        "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 or (for a multi-session analysis) a list of `mask` objects, one for each session
`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 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 `formula` notation
`timecov` | optional dataframe of values of time (occasion-specific) covariate(s).
`sessioncov` | optional dataframe of values of session-specific 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 `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 to be used for parallel processing
`...` | 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", "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 time-varying detector covariates, and secr-models.pdf and secr-overview.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

The default with these detectors is to fit a Poisson distribution.

`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 x-y coordinates
chat | overdispersion of sighting counts Tu, Tm
chatonly | compute overdispersion for Tu and Tm, then exit
contrasts | coding of factor predictors
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 sighting-only model
LLonly | compute one likelihood for values in `start`
miscparm | starting values for extra parameters fitted via userdist function
newdetector | detector type to override detector(traps(capthist))
nsim | number of simulations to compute overdispersion
param | optional parameterisation code
savecall | optionally suppress saving of call
telemetrytype | treat telemetry data as independent, dependent or concurrent
normalize | rescale detection to individual range use
usecov | spatial covariate of use for normalization
userdist | user-provided distance function or matrix

A mark-resight model is fitted if the `markocc` attribute of the capthist ‘traps’ object includes sighting occasions. See the vignette secr-markresight.pdf for a full account.

If `method = "Newton-Raphson"` then `nlm` is used to maximize the log likelihood (minimize the negative log likelihood); otherwise `optim` is used with the chosen method ("BFGS", "Nelder-Mead", 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 variance-covariance 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 multi-session 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(D-hat) > `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 multi-session analyses (it may also slow them down, as data must be copied back and forth). There is presently no benefit for single-session analyses.

Function `par.secr.fit` is an alternative and more effective way to take advantage of multiple cores when fitting several models.

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

### Warning

** Mark-resight data formats and models are experimental in secr 2.10.0 and subject to change **

### Note

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(1-alpha)% 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 Newton-Raphson 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 N-hat, 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` .

### 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 searches. Ecology 92, 2202–2207.

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

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

### Examples

    ## Not run:

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

    ## End(Not run)

[Package secr version 3.2.1 Index]