acs_setup_containers: Setup the detection containers required for the AC*...

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

Setup the detection containers required for the AC* algorithm(s)

Description

This function produces the detection containers required by the acoustic-container (AC) and acoustic-container depth-contour (ACDC) algorithms.

Usage

acs_setup_containers(
  xy,
  detection_range,
  coastline = NULL,
  boundaries = NULL,
  plot = FALSE,
  verbose = TRUE,
  ...
)

Arguments

xy	A SpatialPointsDataFrame object that defines receiver IDs and locations. The data slot must include a dataframe with a column that provides a unique, integer identifier for each receiver (‘receiver_id’). The coordinate reference system should be the Universal Transverse Mercator system with distances in metres (to match detection_range, see below).
detection_range	A number that defines the maximum detection range (m) at which an individual could be detected from a receiver.
coastline	(optional) A SpatialPolygonsDataFrame-class object that defines the coastline in an area. If provided, detection containers are processed to remove any areas on land. Algorithm speed declines with the complexity of the coastline.
boundaries	(optional) An extent object that defines the boundaries of an area within which individuals are assumed to have remained. If provided, acoustic containers are processed to remain within this area.
plot	A logical input that defines whether or not to produce a plot of the area, including receivers, the coastline and the area boundaries (if provided), and acoustic containers. This is useful for checking purposes but it can reduce algorithm speed.
verbose	A logical input that defines whether or not to print messages to the console to relay function progress.
...	Additional arguments passed to get_detection_containers and, ultimately, gBuffer, except byid which is necessarily TRUE.

Details

Given a detection at a particular receiver at a particular time, the detection container defines the boundaries of the area around a receiver within which the individual must have been located (from the perspective of that receiver).

For the AC* algorithms, note that in some coastal settings the representation of detection containers as SpatialPolygonsDataFrame-class objects may cause a mismatch with detection kernels and the bathymetry raster in terms of what is defined as water versus land. At the time of writing, in the AC* algorithms the detection kernels/bathymetry data take precedence, with any grid cells that have a value of NA masked, even if within ‘detection containers’. In the future, these disparities should be resolved by redefining detection containers on the bathymetry grid too.

Value

The function returns a list of SpatialPolygonsDataFrame-class objects, with one element for all numbers from 1 to the maximum receiver number (xy$receiver_id). Any list elements that do not correspond to receivers contain a NULL element. List elements that correspond to receivers contain a SpatialPolygonsDataFrame-class object containing the detection container for that receiver.

Author(s)

Edward Lavender

Examples

#### Define data for acs_setup_containers()
## Define coordinates of receivers as SpatialPointsDataFrame with UTM CRS
# CRS of receiver locations as recorded in dat_moorings
proj_wgs84 <- sp::CRS(SRS_string = "EPSG:4326")
# CRS of receiver locations required
proj_utm <- sp::CRS(SRS_string = "EPSG:32629")
# Define SpatialPoints object
xy_wgs84 <- sp::SpatialPoints(dat_moorings[, c("receiver_long", "receiver_lat")], proj_wgs84)
xy_utm <- sp::spTransform(xy_wgs84, proj_utm)
# Link with receiver IDs to define a SpatialPointsDataFrame
xy_utm <-
  sp::SpatialPointsDataFrame(
    xy_utm,
    dat_moorings[, "receiver_id", drop = FALSE]
  )

#### Example (1): Define a list of containers with specified parameters
# ... (Argument values are small to reduce computation time for examples)
containers <- acs_setup_containers(
  xy = xy_utm,
  detection_range = 500
)
# A list of SpatialPolygonsDataFrames is returned
# with elements from 1:max(xy_utm$receiver_id)
# NULL elements correspond to numbers in this sequence that do not refer to receivers
# Otherwise a SpatialPolygonsDataFrame is returned with all the containers for that receiver
containers

#### Example (2): Visualise the containers produced via plot = TRUE
containers <- acs_setup_containers(
  xy = xy_utm,
  detection_range = 500,
  plot = TRUE
)

#### Example (3): Remove areas of the containers that overlap with coastline
containers <- acs_setup_containers(
  xy = xy_utm,
  detection_range = 500,
  plot = TRUE,
  coastline = dat_coast
)

#### Example (4): Remove areas of the containers beyond a boundary
xy_utm_coords <- sp::coordinates(xy_utm)
boundaries <- raster::extent(
  min(xy_utm_coords[, 1]),
  max(xy_utm_coords[, 1]),
  min(xy_utm_coords[, 2]),
  max(xy_utm_coords[, 2])
)
containers <- acs_setup_containers(
  xy = xy_utm,
  detection_range = 500,
  plot = TRUE,
  coastline = dat_coast,
  boundaries = boundaries
)

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