dot-acs_pl: Intermediate wrapper for '.acs' that supports parallelisation

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

Intermediate wrapper for .acs that supports parallelisation

Description

This function implements the acoustic-container (AC) and acoustic-container depth-contour (ACDC) algorithms. This is called via a front-end function (i.e. ac or acdc). It checks and processes inputs and implements the selected algorithm via calls to .acs. Outputs are returned in a named list.

Usage

.acs_pl(
  acoustics,
  archival = NULL,
  step = 120,
  plot_ts = TRUE,
  bathy,
  detection_containers,
  detection_kernels = NULL,
  detection_kernels_overlap = NULL,
  detection_time_window = 5,
  mobility,
  calc_depth_error = function(...) matrix(c(-2.5, 2.5), nrow = 2),
  normalise = TRUE,
  save_record_spatial = 1L,
  write_record_spatial_for_pf = NULL,
  verbose = TRUE,
  con = "",
  progress = 1L,
  split = NULL,
  cl = NULL,
  varlist = NULL
)

Arguments

acoustics	A dataframe, or a list of dataframes, that contains passive acoustic telemetry detection time series (see dat_acoustics for an example) for a single individual. Each dataframe should contain the following columns: an integer vector of receiver IDs, named ‘receiver_id’; an integer vector of detection indices, named ‘index’; and a POSIXct vector of time stamps when detections were made, named ‘timestamp’. If a list of dataframes is supplied, dataframes must be refer to the detections of a single individual and be ordered by time (e.g., in hourly chunks). In addition, sequential list elements must be linked by identical receiver pairs (i.e., the final receiver at which the individual was detected for any given chunk must be the same as the receiver at which the individual was next detected at the start of the next chunk) because it is only in this specific scenario that information does not need to be shared across time steps (see split). The algorithm will be implemented on each dataframe, termed ‘chunk’, either in sequence or parallel. Any empty or NULL elements will be removed automatically.
archival	For the ACDC algorithm, archival is a dataframe that contains depth time series (see .acs).
step	A number that defines the time step length (s) between consecutive detections (see .acs).
plot_ts	A logical input that defines whether or not to plot movement time series (see .acs).
bathy	A raster that defines the area (for the AC algorithm) or bathymetry (for the ACDC algorithm) across the area within which the individual could have moved (see .acs).
detection_containers	A list of detection containers (see .acs).
detection_kernels	A named list of detection probability kernels (see .acs).
detection_kernels_overlap	A named list of detection probability kernel overlaps, directly from get_detection_containers_overlap. This must contain an element named ‘list_by_receiver’ with the data for each receiver.
detection_time_window	A number that defines the detection time window (see .acs)
mobility	The mobility parameter (see .acs).
calc_depth_error	The depth error function (see .acs).
normalise	A logical input that defines whether or not to normalise maps (see .acs).
save_record_spatial	An integer of the spatial layers to save (see .acs).
write_record_spatial_for_pf	A named list used to write time step-specific maps to file (see .acs).
verbose	A logical variable that defines whether or not to print messages to the console or to file to relay function progress. If con = "", messages are printed to the console (which is only supported if the algorithm is not implemented in parallel: see below); otherwise, they are written to file (see below).
con	If verbose = TRUE, con is character string defines how messages relaying function progress are returned. If con = "", messages are printed to the console (unless redirected by sink), an approach that is only implemented if the function is not implemented in parallel. Otherwise, con defines the directory into which to write .txt files, into which messages are written to relay function progress. This approach, rather than printing to the console, is recommended for clarity, speed and debugging. If the algorithm is implemented step-wise, then a single file is written to the specified directory named acdc_log.txt. If the algorithm is implemented chunk-wise, then an additional file is written for each chunk (named dot_acdc_log_1.txt, dot_acdc_log_2.txt and so on), with the details for each chunk.
progress	(optional) If the algorithm is implemented step-wise, progress is an integer (1, 2 or 3) that defines whether or not to display a progress bar in the console as the algorithm moves over acoustic time steps (1), the ‘archival’ time steps between each pair of acoustic detections (2) or both acoustic and archival time steps (3), in which case the overall acoustic progress bar is punctuated by an archival progress bar for each pair of acoustic detections. This option is useful if there is a large number of archival observations between acoustic detections. Any other input will suppress the progress bar. If the algorithm is implemented for chunks, inputs to progress are ignored and a single progress bar is shown of the progress across acoustic chunks.
split	A character string that defines the (approximate) time unit used to split acoustic time series into chunks (e.g., "12 hours"). If provided, this must be supported by cut.POSIXt (otherwise, a pre-defined list of acoustic time series can be passed to acoustics, e.g., specifying seasonal chunks). If split = NULL and a cluster has been specified (see cl) (and acoustics is a dataframe), then the acoustic time series is automatically split into chunks and the algorithm implemented for each chunk in parallel. In all cases, splitting is subject to the constraint that chunks must join at identical receiver pairs (i.e., the last receiver at which the individual was detected on one chunk must match the first receiver at which the individual was next detected at the start of the next chunk): in these specific scenarios, information does not need to transfer from one time step to the next.
cl, varlist	(optional) Parallelisation options. cl is (a) a cluster object from makeCluster or (b) an integer that defines the number of child processes to implement the algorithm in parallel. If supplied, the algorithm is implemented for each chunk in a list of acoustic time series, either (a) as supplied by the user (if acoustics is a list), (b) as defined by the input to split, or (c) as defined automatically from the number of nodes in the cluster if split = NULL. If cl is supplied, varlist may also be required. This is a character vector of objects to 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.

Value

The function returns an acdc_archive-class object. If a connection to write files has also been specified, an overall log (acdc_log.txt) as well as chunk-specific logs from calls to .acs, if applicable, are written to file.

Author(s)

Edward Lavender

See Also

The front-end functions ac and acdc call this function, which in turn calls .acs. acs_setup_containers defines the detection containers required by this function. acs_setup_mobility is used to examine the assumption of the constant ‘mobility’ parameter. acs_setup_detection_kernels produces detection probability kernels for incorporation into the function. For calls via ac and acdc, acdc_simplify simplifies the outputs and acdc_plot_trace, acdc_plot_record and acdc_animate_record visualise the results.

Examples

# For examples, see ?ac and ?acdc which call this function directly.

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