Skip to contents

Fitting a spatial capture-recapture model

Source: R/fit_acre.R
fit.acre.Rd

Fits an a spatial capture-recapture model to a data object returned by read.acre().

Usage

fit.acre(
  data,
  model = NULL,
  detfn = NULL,
  ss.opts = NULL,
  control.mask = NULL,
  mask = NULL,
  convert.loc2mask = list(),
  tracing = TRUE,
  optim.opts = NULL,
  two.stage = FALSE,
  CL = two.stage
)

Arguments

data

A data object returned by read.acre().

model

A list with named components. Each component name must match a parameter name. The component itself must be a formula specifying the relationship between covariates and the parameter. See the section on model specifications below.

detfn

A character string specifying the detection function to be used. Either "hn" (halfnormal), "hhn" (hazard halfnormal), "hr" (hazard rate), "th" (threshold), "lth" (log-link threshold), or "ss" (signal strength). If "ss" is used, signal strength information must be included in data. See the section below on parameter names for further details.

ss.opts

A list with information required to fit models that include signal strengths as auxiliary detection data. One component must be named cutoff, a detection threshold. An optional component is ss.link, which specifies the relationship between distance and the expected received signal strength. See the section below on signal strength models for further details.

control.mask

a list with elements corresponding to the function create.mask. If provided, and the argument "mask" is not provided, it will be used together with "traps" in the "dat" to expand masks.

mask

an object generated by the function create.mask(), if not provided, this function will create it based on provided traps and control.mask.

convert.loc2mask

a list. When either the arguments of mask or control.mask is provided, the mask will be created by them, and if there is any parameter extended under mask level, this argument could be used to control the process of converting location related covariates to the new mask level data. For any details, could refer to the help document in the function read.acre().

tracing

a logical value. TRUE by default, an indicator of showing the tracing information.

optim.opts

A list with optimisation options. See the section below on optimiser settings.

two.stage

a logical value. FALSE by default. If TRUE, after fitting a model, the partial derivatives, of the ESA for each session, w.r.t. the other parameters, is calculated and returned.

CL

a logical value. FALSE by default. If TRUE, fit a conditional likelihood model, ignoring density parameter estimation.

Model specification

Specify models using the model argument.

(More to put in here)

Parameter names

Parameters fall into three groups:

  • D, density (in calls or animals per hectare).

  • Detection function parameters.

  • Auxiliary data measurement error parameters.

(More to put in here)

Optimiser settings

The fit.acre() function fits a spatial capture-recapture model by numerically maximising the likelihood function with respect to the model parameters. In almost all cases, the optimisation procedure will run without a problem, but in rare cases it might help to adjust how the optimiser works.

The optim.opts argument allows the user to change some optimiser settings. The argument must be a list. Two optional components control parameter-specific optimisation settings:

  • sv: Overrides default parameter start values.

  • fix: Holds parameters constant rather than estimating them via optimisation.

These must be named lists, where component names are parameter names. For sv, the component is a scalar that provides the parameter's start value, and for fix the component is a scalar that provides the fixed value of the parameter. So, for example, sv = list(sigma = 200) will set a start value of 200 m for sigma.

It is not possible to control coefficients for covariates. These always have start values of zero (i.e., no effect of the covariate), and cannot be fixed. The sv component can be named after a parameter that is modelled with covariates. For example, if we include model = list(D = ~ elevation), where elevation is height above sea level in metres, then using sv = list(D = 100) sets the starting values so that density is spatially homogenous at 100 calls per hectare (or 100 animals per hectare, depending on the model). The fix component cannot be used for parameters that are modeled with covariates.

Three additional components control optimiser behaviour:

  • gr.skip: A logical value, and FALSE by default. We use automatic differentiation to speed up numeric optimisation, but in some cases this requires large amounts of RAM. Setting gr.skip to TRUE turns off automatic differentiation, which reduces RAM demands, but, if you have enough RAM, will increase computation time.

  • scale.covs: A logical value, and TRUE by default. If TRUE, covariates are centred and standardised (i.e., we subtract the mean, then divide by the standard deviation) prior to optimisation. This leads to an equivalent model, but optimisation is typically more stable. Regardless of whether scale.covs is TRUE or FALSE, we report estimated coefficients and standard errors on the scale of the original, untransformed covariate.

  • local: A logical value, and FALSE by default, that toggles local integration over activity centres. If TRUE, the likelihood will be computed by only integrating over mask points that are within the buffer distance of all traps that made a detection. This can speed up optimisation, but makes estimates more sensitive to the mask buffer setting.

Signal strength models

There are a few options available for signal strength models.

(More to put in here)