acdc_plot_trace: Plot AC* container dynamics

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

Plot AC* container dynamics

Description

This function visually reconstructs the dynamics of an acoustic-container* (AC*) algorithm (i.e., ac or acdc).

To implement the function, an acdc_record-class object (record) from ac or acdc plus acdc_simplify that defines the outputs of the AC* algorithm is required. A SpatialPointsDataFrame that defines receiver locations and a matrix that defines the daily operational status of each receiver are also required.

For each time step, the function plots the probability surface, the receiver(s) at which the individual was detected and the acoustic containers, illustrating how the expansion, contraction and intersection of acoustic containers capture the set of possible locations for an individual through time.

Usage

acdc_plot_trace(
  record,
  plot = NULL,
  moorings,
  moorings_matrix,
  add_raster = list(),
  add_receiver_1 = list(pch = 4, lwd = 4, col = "darkgreen"),
  add_receiver_2 = list(pch = 4, lwd = 2, col = "darkorange"),
  add_receiver_3 = list(pch = 4, lwd = 1, col = "darkred"),
  add_receiver_n = list(pch = 4, lwd = 2),
  add_container_ap = list(col = "darkgreen"),
  add_container_an = list(col = "darkgreen"),
  add_container_b = list(col = "darkorange"),
  add_container_c = list(col = scales::alpha("forestgreen", 0.5), density = 20),
  add_coastline = list(),
  add_main = list(),
  ...,
  par_param = list(),
  png_param = list(),
  prompt = TRUE
)

Arguments

record	A acdc_record-class object from ac or acdc plus acdc_simplify.
plot	An integer vector that defines the time steps for which to make plots. If plot = NULL, the function will make a plot for all time steps for which the necessary information is available in record.
moorings	A SpatialPointsDataFrame that defines receiver locations (in the Universe Transverse Mercator coordinate reference system) and receiver IDs (in a column named ‘receiver_id’).
moorings_matrix	A matrix that defines, for each day of the study (rows) and each receiver (columns), receivers' operational status (see make_matrix_receivers).
add_raster	A named list of arguments, passed to add_sp_raster, to plot the location-probability surface.
add_receiver_1, add_receiver_2, add_receiver_3, add_receiver_n	Named lists of arguments, passed to points, to customise the appearance of receivers. add_receiver_1 controls the appearance of the ‘current’ receiver (at which the individual was last or has just been detected); add_receiver_2 controls the appearance of the receiver at which the individual was next detected; add_receiver_3 controls the appearance of the third receiver at which the individual was detected; and add_receiver_n controls the appearance of all remaining active receivers.
add_container_ap, add_container_an, add_container_b, add_container_c	Named lists of arguments that control the appearance of acoustic containers. (container_ap defines the boundaries of the individual's location from the perspective of its previous location; container_an defines the boundaries of the individual's location at the moment of detection from the perspective of the receiver that recorded the detection; container_b defines the boundaries of the individual's location from the perspective of the receiver at which the individual was next detected; and container_c defines the boundaries of the individual's location integrated across all of these perspectives; see acdc_record-class.) add_container_ap,add_container_an and add_container_b are passed to lines,SpatialPolygons-method and add_container_c is passed to plot.
add_coastline	A named list of arguments, passed to plot, to add coastline to each plot.
add_main	A named list of arguments, passed to mtext, to customise the appearance of the plot title. Default plot titles are structured as follows: ‘Map for t = cumulative time step (detection time step [intermediate time step] time stamp’. When the intermediate time step is one, the individual is detected. At subsequent intermediate time steps, acoustic containers expand and contract.
...	Additional plot customisation options passed to pretty_map.
par_param	A named list of arguments, passed to par, to set the plotting window.
png_param	(optional) A named list of arguments, passed to png, to save plots to file. If supplied, the plot for each time step is saved separately. The ‘filename’ argument should be the directory in which plots are saved. Plots are then saved as "1.png", "2.png" and so on. If supplied, prompt is ignored (see below).
prompt	If png_param is not specified, prompt is a logical variable that defines whether or not to pause function execution between plots and between containers within plots to facilitate interpretation.

Value

The function returns, for each time step, a plot of the probability surface and acoustic containers.

Author(s)

Edward Lavender

See Also

ac and acdc implement the AC and ACDC algorithms and acdc_simplify simplifies the results. acdc_plot_record and acdc_animate_record provide additional visualisation routines.

Examples

#### Prepare example AC algorithm outputs with spatial files

## Define example time series
id <- 25
acc <- dat_acoustics[dat_acoustics$individual_id == id, ]
acc$timestamp <- lubridate::round_date(acc$timestamp, "2 mins")
acc$key <- paste0(acc$timestamp, "-", acc$receiver_id)
acc <- acc[!duplicated(acc$key), ][1:20, ]

## Define receiver locations ('moorings' SPDF) and activity status matrix
# Receiver locations
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)
moorings <- sp::SpatialPointsDataFrame(xy, data = dat_moorings)
# Daily activity status matrix
as_POSIXct <- function(x) as.POSIXct(paste0(x, "00:00:00"), tz = "UTC")
moorings_mat <- make_matrix_receivers(dat_moorings,
  delta_t = "days",
  as_POSIXct = as_POSIXct
)

## Prepare grid
# We will use a regular, relatively high resolution grid,
# focused on a small area around the receivers at which the ID was detected
grid <- raster::raster(raster::extent(dat_gebco),
  res = c(25, 25),
  crs = raster::crs(dat_gebco)
)
grid <- raster::resample(dat_gebco, grid)
ext <-
  raster::extent(
    rgeos::gBuffer(moorings[moorings$receiver_id %in% acc$receiver_id, ],
      width = 10000
    )
  )
grid <- raster::crop(grid, ext)
grid <- raster::trim(grid)
raster::plot(grid)

## Define detection containers/probability kernels
# Define detection containers
moorings <- raster::crop(moorings, grid)
dat_container <- acs_setup_containers(
  xy = moorings,
  detection_range = 425,
  coastline = dat_coast,
  boundaries = ext,
  plot = TRUE,
  resolution = 10,
  verbose = TRUE
)
# Define detection container overlaps
containers_spdf <- do.call(raster::bind, plyr::compact(dat_containers))
containers_spdf@data <- dat_moorings
dat_containers_overlaps <-
  get_detection_containers_overlap(
    containers = containers_spdf,
    services = NULL
  )
# Define detection probability kernels
calc_dpr <-
  function(x) {
    ifelse(x <= 425, stats::plogis(2.5 + -0.02 * x), 0)
  }
dat_kernels <- acs_setup_detection_kernels(
  xy = moorings,
  services = NULL,
  containers = dat_containers,
  overlaps = dat_containers_overlaps,
  calc_detection_pr = calc_dpr,
  bathy = grid
)

## Implement AC algorithm
out_ac <- ac(
  acoustics = acc,
  step = 120,
  bathy = grid,
  detection_containers = dat_containers,
  detection_kernels = dat_kernels,
  detection_kernels_overlap = dat_containers_overlaps,
  mobility = 200,
  save_record_spatial = NULL
)

## Simplify outputs
record <- acdc_simplify(out_ac)

#### Example (1): Implement the function with default arguments
if (interactive()) {
  acdc_plot_trace(record, 1:10, moorings, moorings_mat)
}

#### Example (2): Customise plot via add_* arguments and ...
if (interactive()) {
  acdc_plot_trace(record, 1:10, moorings, moorings_mat,
    add_raster =
      list(plot_method = raster::plot, legend = FALSE),
    add_coastline =
      list(x = dat_coast, col = scales::alpha("dimgrey", 0.5)),
    xlim = c(699000, 711000),
    ylim = c(6250000, 6269500)
  )
}

#### Example (3): Save plots to file via the png_param argument
con <- paste0(tempdir(), "/acdc_trace/")
if (!dir.exists(con)) dir.create(con)
acdc_plot_trace(record, 1:10, moorings, moorings_mat,
  add_raster =
    list(plot_method = raster::plot, legend = FALSE),
  add_coastline =
    list(x = dat_coast, col = scales::alpha("dimgrey", 0.5)),
  xlim = c(699000, 711000),
  ylim = c(6250000, 6269500),
  png_param = list(filename = con),
  prompt = FALSE
)
list.files(con)

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