details {secr} | R Documentation

## Detail Specification for secr.fit

### Description

The function `secr.fit` allows many options. Some of these are used infrequently and have been bundled as a single argument `details` to simplify the documentation. They are described here.

### Detail components

`details$autoini` specifies the session from which to compute starting values (multi-session data only; default 1)

`details$centred` = TRUE causes coordinates of both traps and mask to be centred on the centroid of the traps, computed separately for each session in the case of multi-session data. This may be necessary to overcome numerical problems when x- or y-coordinates are large numbers. The default is not to centre coordinates.

`details$chat` optionally specifies the overdispersion of unmarked sightings Tu and unidentified marked sightings Tm. It is used only for mark-resight models, and is usually computed within `secr.fit` (`details$nsim > 0`), but may be provided by the user. For a single session 'chat' is a vector of length 2; for multiple sessions it is a 2-column matrix.

`details$chatonly` = TRUE used with `details$nsim > 0` causes the overdispersion statistics for sighting counts Tu and Tm to be estimated and returned as a vector or 2-column matrix (multi-session models), with no further model fitting.

`details$contrasts` may be used to specify the coding of factor predictors. The value should be suitable for the 'contrasts.arg' argument of `model.matrix`. See ‘Trend across sessions’ in secr-multisession.pdf for an example.

`details$debug` is an integer code used to control the printing of intermediate values (1,2) and to switch on the R code browser (3). In ordinary use it should not be changed from the default (0).

`details$distribution` specifies the distribution of the number of individuals detected n; 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". The component ‘distribution’ may also take a numeric value larger than nrow(capthist), rather than "binomial" or "poisson". The likelihood then treats n as a binomial draw from a superpopulation of this size, with consequences for the variance of density estimates. This can help to reconcile MLE with Bayesian estimates using data augmentation.

`details$fixedbeta` may be used to fix values of beta parameters. It should be a numeric vector of length equal to the total number of beta parameters (coefficients) in the model. Parameters to be estimated are indicated by NA. Other elements should be valid values on the link scale and will be substituted during likelihood maximisation. Check the order of beta parameters in a previously fitted model.

`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. See also method = "none" below.

`details$ignoreusage` = TRUE causes the function to ignore usage (varying effort) information in the traps component. The default (`details$ignoreusage` = FALSE) is to include usage in the model.

`details$intwidth2` controls the half-width of the interval searched by optimise() for the maximum likelihood when there is a single parameter. Default 0.8 sets the search interval to (0.2s, 1.8s) where s is the ‘start’ value.

`details$knownmarks` = FALSE causes secr.fit to fit a zero-truncated sightings-only model that implicitly estimates the number of marked individuals, rather than inferring it from the number of rows in the capthist object.

`details$LLonly` = TRUE causes the function to returns a single evaluation of the log likelihood at the ‘start’ values.

`details$miscparm` (default NULL) is an optional numeric vector of starting values for additional parameters used in a user-supplied distance function (see ‘userdist’ below). If the vector has a names attribute then the names will be used for the corresponding coefficients (‘beta’ parameters) which will otherwise be named ‘miscparm1’, miscparm2' etc. These parameters are constant across each model and do not appear in the model formula, but are estimated along with other coefficients when the likelihood is maximised. Any transformation (link function) etc. is handled by the user in the userdist function. The coefficients appear in the output from `coef.secr` and `vcov.secr`, but not `predict.secr`.

`details$newdetector` specifies a detector type to use for this fit, replacing the previous `detector(traps(capthist))`. The value may be a vector (one value per occasion) or for multi-session data, a list of vectors. A scalar value (e.g. "proximity") is otherwise used for all occasions and sessions. The true detector type is usually known and will be specified in the 'traps' attribute; `newdetector` is useful in simulation studies that examine the effect of misspecification. The capthist component of the output from secr.fit has the new type.

`details$nsim` specifies the number of replicate simulations to perform to estimate the overdispersion statistics for the sighting counts Tu and Tm. See also `details$chat` and `details$chatonly`.

`details$param` chooses between various parameterisations of the SECR model. The default `details$param = 0` is the formulation in Borchers and Efford (2008) and later papers.

`details$param = 1` was once used to select the Gardner & Royle parameterisation of the detection model (p0, σ; Gardner et al. 2009) when the detector type is ‘multi’. This parameterisation was discontinued in 2.10.0.

`details$param = 2` selects parameterisation in terms of (esa(g_0, σ), σ) (Efford and Mowat 2014).

`details$param = 3` selects parameterisation in terms of (a_0(lambda0, σ), σ) (Efford and Mowat 2014). This parameterization is used automatically if a0 appears in the model (e.g., a0 ~ 1).

`details$param = 4` selects parameterisation of sigma in terms of the coefficient sigmak and constant c (sigma = sigmak / D^0.5 + c) (Efford et al. in prep). If c is not included explicitly in the model (e.g., c ~ 1) then it is set to zero. This parameterization is used automatically if sigmak appears in the model (e.g., sigmak ~ 1)

`details$param = 5` combines parameterisations (3) and (4) (first compute sigma from D, then compute lambda0 from sigma).

`details$savecall` determines whether the full call to `secr.fit` is saved in the output object. The default is TRUE except when called by `par.secr.fit` as names in the call are then evaluated, causing the output to become unwieldy.

`details$splitmarked` determines whether the home range centre of marked animals is allowed to move between the marking and sighting phases of a spatial capture–mark–resight study. The default is to assume a common home-range centre (`splitmarked = FALSE`).

`details$telemetrytype` determines how telemetry data in the attribute ‘xylist’ are treated. ‘none’ causes the xylist data to be ignored. ‘dependent’ uses information on the sampling distribution of each home-range centre in the SECR likelihood. ‘concurrent’ does that and more: it splits capthist according to telemetry status and appends all-zero histories to the telemetry part for any animals present in xylist. The default is ‘concurrent’.

`details$normalize` = TRUE rescales detection so that individual range use sums to 1.0 (cf Royle et al. 2013)

`details$usecov` selects the mask covariate to be used for normalization. NULL limits denominator for normalization to distinguishing habitat from non-habitat.

`details$userdist` is either a function to compute non-Euclidean distances between detectors and mask points, or a pre-computed matrix of such distances. The first two arguments of the function should be 2-column matrices of x-y coordinates (respectively k detectors and m mask points). The third argument is a habitat mask that defines a non-Euclidean habitat geometry (a linear geometry is described in documentation for the package ‘secrlinear’). The matrix returned by the function must have exactly k rows and m columns. When called with no arguments the function should return a character vector of names for the required covariates of ‘mask’, possibly including the dynamically computed density 'D' and a parameter ‘noneuc’ that will be fitted. A slightly expanded account is at userdist, and full documentation is in the separate document secr-noneuclidean.pdf.

**Do not use ‘userdist’ for polygon or transect detectors**

### References

Efford, M. G. and Mowat, G. (2014) Compensatory heterogeneity in capture–recapture data.Ecology 95, 1341–1348.

Gardner, B., Royle, J. A. and Wegan, M. T. (2009) Hierarchical models for estimating density from DNA mark-recapture studies. Ecology 90, 1106–1115.

Royle, J. A., Chandler, R. B., Sun, C. C. and Fuller, A. K. (2013) Integrating resource selection information with spatial capture–recapture. Methods in Ecology and Evolution 4, 520–530.

### See Also

`secr.fit` , userdist

### Examples

    ## Not run:
    ## Demo of miscparm and userdist
    ## We fix the usual 'sigma' parameter and estimate the same
    ## quantity as miscparm[1]. Differences in CI reflect the implied use
    ## of the identity link for miscparm[1].

    mydistfn3 <- function (xy1,xy2, mask) {
        if (missing(xy1)) return(character(0))
        xy1 <- as.matrix(xy1)
        xy2 <- as.matrix(xy2)
        miscparm <- attr(mask, 'miscparm')
        distmat <- edist(xy1,xy2) / miscparm[1]
        distmat
    }

    fit0 <- secr.fit (captdata)
    fit <- secr.fit (captdata, fixed = list(sigma=1), details =
        list(miscparm = c(sig = 20), userdist = mydistfn3))
    predict(fit0)
    coef(fit)

    ## End(Not run)

[Package secr version 3.2.1 Index]