sim_detections: Simulate detections
In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

sim_detections

R Documentation

Simulate detections

Description

This function simulates detections at passive acoustic telemetry receivers under a detection model that depends on distance. To implement the function, the underlying movement path that gives rise to detections (or not) must be supplied (via path) along with the locations of receivers (xy) at which detections can be made. At each point along the movement path (i.e., time step), the function calculates the distances from that point to all of the receivers and evaluates a user-supplied detection probability function, based on distance, to determine detection probability at each receiver. The function then simulates binary detection outcomes from a binomial distribution conditional on this probability, and returns these in a matrix with one simulated outcome for each time step and receiver.

Usage

sim_detections(
  path,
  xy,
  crs = NA,
  calc_detection_pr,
  by_timestep = FALSE,
  delta_t = NULL,
  seed = NULL,
  plot = TRUE,
  jitter = function(n) stats::rnorm(n, 0, 0.05),
  add_prob = list(col = "royalblue", pch = 3, cex = 0.5),
  xlim = c(0, 1000),
  verbose = TRUE,
  ...
)

Arguments

`path`	A two-column matrix of the coordinates of the movement path (x, y).
`xy`	A two-column matrix of the coordinates of receivers (x, y).
`crs`	A `CRS` object that defines the coordinate reference system (CRS) for `path` and `xy` (if applicable).
`calc_detection_pr`	A function that takes in a vector of distances and returns a vector of detection probabilities.
`by_timestep`	A logical variable that defines whether or not `calc_detection_pr` needs to be applied to each time step separately. This may be necessary if some of the parameters of the detection model are vectors (see Examples).
`delta_t`	(optional) An integer that defines the number of time steps over which to aggregate detections. If provided, detections are summed over each `delta_t` interval and returned along with averaged distances and probabilities (see Value).
`seed`	An integer that is used to set the seed to enable reproducible simulations (see `set.seed`).
`plot`	A logical variable that defines whether or not to plot detections (and probabilities) against distances.
`jitter`, `add_prob`, `xlim`, `...`	Plot customisation options. `jitter` is a function that jitters `n` simulated outcomes (0, 1) in the vertical direction. `add_prob` is a named list of arguments, passed to `points`, used to customise the addition of calculated probabilities to the plot. (`add_prob = NULL` suppresses the addition of probabilities to the plot.) `xlim` is a vector of x axis limits. By default, `xlim = c(0, 1000)` to improve resolution in the area of the plot that is of interest (under a Universal Transverse Mercator CRS, for most realistic detection probability functions, detection probability beyond 1000 will be negligible) and plotting speed. Additional arguments can be passed to `pretty_plot` to customise the plot via `...`.
`verbose`	A logical variable that defines whether or not to print messages to the console to relay function progress.

Details

The function assumes that the individual transmits an acoustic signal which has the capacity to be detected at each time step. In reality, acoustic transmitters are often programmed with a randomly varying delay, but this is not currently implemented. The function also assumes that all receivers that are supplied are able to make detections. If the receivers at which an individual could be detected change over time, it may be necessary to apply the function iteratively or post-process the outcomes to ensure that individuals are not detected at inactive receivers.

For coupled simulation–analysis workflows (such as sim_array, sim_path_sa and sim_detections plus ac, dc, acdc and pf), it is important that receiver locations (from sim_array) and individual locations (from sim_path_sa) are represented on the raster grid used to reconstruct simulated movements before simulating detections. Receiver locations and movement distances must remain admissible according to the movement model when translated on the grid. Grid resolution should be sufficiently high to represent effectively simulated movement probabilities and detection probabilities.

Value

If delta_t = NULL, then function returns a named list with three matrices that define, for each path position (rows) and each receiver (columns), (a) the distance of that position from each receiver (‘dist_mat’), (b) the probability of detection at that receiver (‘prob_mat’) and (c) the simulated outcome (0, no detection; 1, detection) (‘det_mat’). If delta_t is specified, then the function returns a list with a ‘raw’ and an ‘agg’ element. The raw elements contains the matrices described above; the ‘agg’ element contains the aggregated versions of these matrices, with detections summed over each delta_t interval and distances and probabilities averaged (using the arithmetic mean) over each interval. If plot = TRUE, the function also returns a plot of the (raw) detections (0, 1) and, if specified, the corresponding probabilities.

Author(s)

Edward Lavender

Examples

#### Step (1) Simulate an array in an area
array_ls <- sim_array(
  boundaries = raster::extent(dat_coast),
  coastline = dat_coast,
  n_receivers = 100,
  arrangement = "regular",
  seed = 1
)
raster::lines(dat_coast)

#### Step (2) Simulate a movement path in this area
n <- 500
path_ls <- sim_path_sa(
  n = n,
  sim_step = function(...) stats::rgamma(1, shape = 25, scale = 25),
  area = array_ls$array$sea,
  seed = 1,
  plot = FALSE
)
prettyGraphics::add_sp_path(path_ls$xy_mat, col = viridis::viridis(n), length = 0.02)

#### Step (3) Simulate detections
## (A) Extract path and receiver coordinates from simulated outcomes above
path <- path_ls$xy_mat
xy <- array_ls$array$xy
xy <- sp::coordinates(xy)
## (B) Simulate detections under different probability functions (see below).

#### Example (1) Threshold probability function
# Define detection pr function
calc_detection_pr <- function(dist) ifelse(dist < 425, 1, 0)
# Simulate detections
dets_sim <- sim_detections(
  path = path,
  xy = xy,
  calc_detection_pr = calc_detection_pr
)
# The function returns a list of matrices that define the distances,
# ... probabilities and detections for each time stamp (row) and each receiver
# ... (column)
utils::str(dets_sim)
# Examine probabilities
table(dets_sim$prob_mat)
# We can also aggregate detections via delta_t
dets_sim <- sim_detections(
  path = path,
  xy = xy,
  calc_detection_pr = calc_detection_pr,
  delta_t = 10
)
# In this case, the function returns a list with 'agg' and 'raw' elements
# ... The 'agg' elements contain aggregated matrices and the 'raw' elements
# ... contain the matrices described above.
utils::str(dets_sim)
table(dets_sim$raw$det_mat)
table(dets_sim$agg$det_mat)

#### Example (2) Logistic probability function
calc_detection_pr <- function(dist) stats::plogis(2.5 + -0.01 * dist)
dets_sim <- sim_detections(
  path = path,
  xy = xy,
  calc_detection_pr = calc_detection_pr
)

#### Example (3) Spatially varying probability function
# Define spatially varying beta parameter (e.g., reflecting 2 habitat types)
area <- array_ls$array$area
area_r <- raster::raster(
  x = raster::extent(area),
  crs = raster::crs(area)
)
area_r[] <- 0L
beta_surface <- sim_surface(
  blank = area_r,
  n = 2L,
  sim_values = list(
    function(n) -0.05,
    function(n) -0.01
  ),
  mask = array_ls$array$sea
)
# Extract receiver specific beta values
xy_sp <- sp::SpatialPoints(xy, proj4string = raster::crs(area_r))
beta <- raster::extract(beta_surface, xy_sp)
# Visualise simulated detection probability surface at some suitable distances
pp <- graphics::par(mfrow = c(2, 2))
lapply(c(0, 50, 100, 500), function(dist) {
  r <- raster::calc(beta_surface, function(beta) stats::plogis(2.5 + beta * dist))
  raster::plot(r)
})
graphics::par(pp)
# Define detection probability function
calc_detection_pr <- function(dist) stats::plogis(2.5 + beta * dist)
# Simulate detections
# ... Define by_timestep = TRUE so that that distances from each receiver
# ... are combined appropriately with beta values for each receiver
dets_sim <- sim_detections(
  path = path,
  xy = xy,
  calc_detection_pr = calc_detection_pr,
  by_timestep = TRUE
)

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.