get_detection_containers_envir: Sample environmental conditions around receivers

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

Sample environmental conditions around receivers

Description

This function is used to sample environmental conditions from within the detection containers of receivers. To implement the function, a SpatialPoints object that defines receiver locations (xy) must be provided, along with the detection range (detection_range) of receivers. This information is used to define detection containers, via get_detection_containers. Within each receiver's container, all values of an environmental variable, or a random sample of values, are extracted from a user-defined raster (envir). Under random sampling, values can be sampled according to a detection probability function (sample_probs). The function returns a list of dataframes, one for each receiver, that include the sampled values.

Usage

get_detection_containers_envir(
  xy,
  detection_range,
  coastline,
  plot = FALSE,
  envir,
  sample_size = NULL,
  sample_replace = TRUE,
  sample_probs = NULL,
  cl = NULL,
  varlist = NULL,
  verbose = TRUE,
  ...
)

Arguments

xy, detection_range, coastline, plot, ...	Arguments required to calculate and visualise detection containers via get_detection_containers; namely, receiver locations (xy), the detection range (detection_range), barriers to detection (coastline) and whether or not to plot the containers (plot). Additional arguments can be passed via ... but note that byid is necessarily TRUE and should not be provided.
envir	A raster that defines the values of an environmental variable across the study area. The coordinate reference system should be the Universal Transverse Mercator system.
sample_size	(optional) An integer that defines the number of samples of the environmental variable to draw from the area around each receiver (see the ‘size’ argument of sample). If this is provided, sample_size samples are taken from this area; otherwise, all values are extracted.
sample_replace	(optional) If sample_size is specified, sample_replace is a logical input that defines whether to implement sampling with (sample_replace = TRUE, the default) or without (sample_replace = FALSE) replacement (see the ‘replace’ argument of sample).
sample_probs	(optional) If sample_size is specified, sample_probs is a function that calculates the detection probability given the distance (m) between a cell and a receiver.
cl, varlist	(optional) Parallelisation options. cl is (a) a cluster object from makeCluster or (b) an integer that defines the number of child processes. varlist is a character vector of variables for export (see cl_export). Exported variables must be located in the global environment. If a cluster is supplied, the connection to the cluster is closed within the function (see cl_stop). For further information, see cl_lapply and flapper-tips-parallel.
verbose	A logical variable that defines whether or not relay messages to the console to monitor function progress.

Value

The function returns a list of dataframes (one for each element in xy; i.e., each receiver), each of which includes the cell IDs of envir from which values were extracted (‘cell’), the value of the environmental variable in that cell (‘envir’) and, if applicable, the distance between that cell and the receiver (‘dist’, m) and the detection probability in that cell (‘prob’).

Author(s)

Edward Lavender

Examples

#### Define receiver locations as a SpatialPoints object with a UTM CRS
proj_wgs84 <- sp::CRS(SRS_string = "EPSG:4326")
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
xy <- sp::SpatialPoints(
  dat_moorings[, c("receiver_long", "receiver_lat")],
  proj_wgs84
)
xy <- sp::spTransform(xy, proj_utm)
xy@data <- as.data.frame(xy)

#### Example (1): Extract all depth values within each receiver's container
depths_by_container <-
  get_detection_containers_envir(
    xy = xy,
    detection_range = 425,
    coastline = dat_coast,
    envir = dat_gebco
  )
# The function returns a list of dataframes, one for each receiver
# ... with the cell IDs and the value of the environmental variable
utils::str(depths_by_container)
# Collapse the list and compare conditions across receivers
depths_by_container <-
  lapply(1:length(depths_by_container), function(i) {
    d <- depths_by_container[[i]]
    d$receiver_id <- dat_moorings$receiver_id[i]
    return(d)
  })
depths_by_container <- dplyr::bind_rows(depths_by_container)
prettyGraphics::pretty_boxplot(
  depths_by_container$receiver_id,
  depths_by_container$envir
)

#### Example (2): Extract a random sample of values
# (We'll keep the values small for speed)
depths_by_container <-
  get_detection_containers_envir(
    xy = xy,
    detection_range = 425,
    coastline = dat_coast,
    envir = dat_gebco,
    sample_size = 2
  )
utils::str(depths_by_container)

#### Example (3) Extract a random sample of values with weighted probabilities
# Define detection probability function based only on distance
calc_detection_pr <-
  function(dist) {
    dpr <- get_detection_pr(
      distance = dist,
      beta_0 = 2.5,
      beta_1 = -0.01,
      inv_link = stats::plogis,
      output = 2L
    )
    return(dpr)
  }
# Implement sampling with replacement according to detection probability
depths_by_container <-
  get_detection_containers_envir(
    xy = xy,
    detection_range = 425,
    coastline = dat_coast,
    envir = dat_gebco,
    sample_size = 2,
    sample_probs = calc_detection_pr
  )
# Each element of the outputted list includes the 'cell' and 'envir' column
# ... as well as 'dist' and 'prob' that define the distance of that cell
# ... from the location in xy and the corresponding detection probability
# ... at that distance respectively
utils::str(depths_by_container)

#### Example (4) Sampling without replacement via sample_replace = FALSE
depths_by_container <-
  get_detection_containers_envir(
    xy = xy,
    detection_range = 425,
    coastline = dat_coast,
    envir = dat_gebco,
    sample_size = 2,
    sample_probs = calc_detection_pr,
    sample_replace = FALSE
  )
utils::str(depths_by_container)

#### Example (5) Parallelise the algorithm via cl and varlist arguments
depths_by_container <-
  get_detection_containers_envir(
    xy = xy,
    detection_range = 425,
    coastline = dat_coast,
    envir = dat_gebco,
    sample_size = 2,
    sample_probs = calc_detection_pr,
    sample_replace = FALSE,
    cl = parallel::makeCluster(2L),
    varlist = c("dat_gebco", "calc_detection_pr")
  )
utils::str(depths_by_container)

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