sim.capt: Simulating SCR data

In b-steve/ascr: Acoustic spatial capture-recapture

Simulating SCR data

Description

Simulates SCR capture histories and associated additional information in the correct format for use with the function fit.ascr. If fit is provided then no other arguments are required. Otherwise, at least traps, mask, and pars are needed.

Usage

sim.capt(
  fit = NULL,
  traps = NULL,
  mask = NULL,
  popn = NULL,
  infotypes = character(0),
  detfn = "hn",
  pars = NULL,
  ss.opts = NULL,
  cue.rates = NULL,
  survey.length = NULL,
  freq.dist = "edf",
  sound.speed = 330,
  ihd.surf = NULL,
  test.detfn = FALSE,
  first.only = FALSE,
  keep.locs = FALSE,
  keep.ids = FALSE,
  ...
)

Arguments

fit	A fitted ascr model object which provides the additional information types, detection function, and parameter values from which to generate capture histories.
traps	A matrix with two columns. Each row provides Cartesian coordinates for the location of a detector. Alternatively, this can be a list of such matrices if detections from multiple detector arrays (or ‘sessions’) are being used to fit a single model.
mask	A matrix with two columns, providing x- and y-coordinates respectively. The extreme x- and y-coordinates define the rectangle in which individuals' locations are simulated.
popn	A matrix with two columns, providing x- and y-coordinates of the animal locations.
infotypes	A character vector indicating the type(s) of additional information to be simulated. Elements can be a subset of "bearing", "dist", "toa", and "mrds" (NOTE: "mrds" not yet implemented). If signal strength information is required, specify detfn as "ss" rather than including it here.
detfn	A character string specifying the detection function to be used. Options are "hn" (halfnormal), "hr" (hazard rate), "th" (threshold), "lth" (log-link threshold), or "ss" (signal strength).
pars	A named list. Component names are parameter names, and each component is the value of the associated parameter. A value for the parameter D, animal density (or call density, if it an acoustic survey) must always be provided, along with values for parameters associated with the chosen detection function and additional information type(s).
ss.opts	Options for models using the signal strength detection function. See 'Details' below.
cue.rates	A vector of call frequencies from which a distribution for the number of emitted calls for each individual is fitted. If scalar, all individuals make the same number of calls. If Inf, first.only must be TRUE, and all individuals keep making calls until the first is detected.
survey.length	The length of a cue-based survey.
freq.dist	A character string, either "edf" or "norm", which specifies how the distribution function of the call frequencies should be estimated. If "edf", then the distribution of call frequencies is estimated using the empirical distribution function. If "norm", then a normal distribution is fitted to the call frequencies using the sample mean and variance. If cue.rates is scalar then this is ignored, and all individuals make the same number of calls. See 'Details' below for information on how call frequencies are rounded.
sound.speed	The speed of sound in metres per second. Defaults to 330 (approximately the speed of sound in air). Only used when "toa" is a component name of capt.
ihd.surf	A list with a vector for each session containing a value for animal density at each mask point. Only required to simulate inhomogeneous density surfaces.
test.detfn	Logical value, if TRUE, tests detection function to aid debugging.
first.only	Only keep the first detection for each individual.
keep.locs	Logical, if TRUE, the locations of individuals in the simulated population are retained. In this case, the capture histories and auxiliary information are kept in a component capt of the returned list, locations of detected individuals are kept in a component capt.locs, and locations of all individuals in the population are kept in a component popn.locs. In this case, the capture histories and auxiliary information are kept in a component capt of the returned list, and ID numbers of detected individuals are kept in a component capt.ids
keep.ids	Logical, if TRUE, the ID number of detected individuals are retained.
...	Other arguments (mostly for back-compatibility).

Details

See documentation for the function fit.ascr for information on the parameters corresponding to the different detection functions, and to different types of additional information.

Simulated call frequencies are not always integers, e.g. when freq.dist is "norm", or when freq.dist is "edf" and the call frequencies used to fit the model fit are not all integers. In this case, if freq.dist is "edf", then simulated call frequencies are rounded at random as follows: Let x be the fraction part of the number, then the call frequency is rounded up with probability x and rounded down with probability 1 - x. For example, a value of 8.1 will be rounded to 9 with probability 0.1, and rounded to 8 with probability 0.9.

If cue.rates is Inf then all simulated individuals will be detected. To generate sensible capture histories then both a lower and upper cutoff must be supplied in ss.opts. In this case, individuals continue to emit calls until one is detected above the lower cutoff by at least one microphone. This individual is then incorporated into the resulting capture history only if the loudest received signal strength is also above the upper cutoff.

Value

A list with named components, each corresponding to a data type listed in infotypes. Each component is a matrix where each row corresponds to each detected individual, and each column corresponds to a trap (or detector). The elements in the matrix indicate detection, and provide simulated values of the additional information requested. This object can be used as the capt argument for the function fit.ascr.

Examples

## Simulating based on model fits.
simple.capt <- sim.capt(example.data$fits$simple.hn)
bearing.capt <- sim.capt(example.data$fits$bearing.hn)
## Simulating from provided parameter values.
new.capt <- sim.capt(traps = example.data$traps, mask = example.data$mask, infotypes = c("bearing", "dist"), detfn = "hr",
                     pars = list(D = 2500, g0 = 0.9, sigma = 3, z = 2, kappa = 50, alpha = 10))

b-steve/ascr documentation built on Aug. 15, 2022, 2:38 p.m.