ac | R Documentation |
This function implements the acoustic-container (AC) algorithm. To implement the function, a dataframe (or list) of passive acoustic telemetry detections is required (acoustics
). At each time step, the algorithm integrates information from past and future acoustic detections in the form of acoustic containers to determine the possible locations of an individual in an area (see Details).
Under the default options, the approach is implemented step-wise (i.e., step-by-step across the whole time series). The result is a named list of outputs, including a record of the results for each time step, as well as a cumulative map of the expected proportion of time spent in each part of the study area across the whole time series. Alternatively, the approach can be implemented chunk-wise, in which case the acoustic time series is split into chunks (e.g., hourly, daily, monthly segments) and the algorithm is implemented within each chunk step-by-step. The main benefits of this approach are that it can be used to reconstruct putative patterns in space use over biologically meaningful periods separately and/or the chunk-wise implementation can be parallelised, improving computation time. (Chunk-wise results results are easily combined across the duration of the original time series without the loss of information via acdc_simplify
.). This option is implemented if (a) a list, rather than a dataframe, of acoustic detections is provided (via acoustics
); (b) the user specifies that the time series should be split into chunks of a particular duration before the algorithm is initiated (via the split
argument); and/or (c) the algorithm is implemented in parallel via cl
, in which case the acoustic time series is split (if necessary) into user-defined or automatically defined chunks prior to computation. In this case, the result is a named list of outputs, as described above, but in which the results for each chunk are returned separately. If the chunks have been implemented simply to improve computation time via parallelisation, then the maps of space use for each chunk can be combined easily to generate a single, overall map of space use via acdc_simplify
.
ac(
acoustics,
step,
bathy,
plot_ts = TRUE,
detection_containers,
detection_kernels = NULL,
detection_kernels_overlap = NULL,
detection_time_window = 5,
mobility,
normalise = TRUE,
save_record_spatial = 1L,
write_record_spatial_for_pf = NULL,
save_args = TRUE,
verbose = TRUE,
con = "",
progress = 1L,
split = NULL,
cl = NULL,
varlist = NULL
)
acoustics |
A dataframe, or a list of dataframes, that contains passive acoustic telemetry detection time series (see |
step |
A number that defines the time step length (s). The time series is rounded to the nearest |
bathy |
A |
plot_ts |
A logical input that defines whether or not to the plot detection time series before the algorithm is initiated. |
detection_containers |
A list of detection containers, with one element for each number from |
detection_kernels |
A named list of detection probability kernels, from |
detection_kernels_overlap |
(optional) A named list, from |
detection_time_window |
(optional) A number that defines the maximum duration (s) between consecutive detections at different receivers such that they can be said to have occurred at ‘effectively the same time’. This indicates that the same transmission was detected by multiple receivers. If |
mobility |
A number that defines the (Euclidean) distance (m) that an individual could move in the time steps between sequential detections (see also |
normalise |
A logical variable that defines whether or not to normalise the map of possible locations at each time step. (The cumulative surface can be normalised via |
save_record_spatial |
An integer vector that defines the time steps for which to save a record of the spatial information from each time step. |
write_record_spatial_for_pf |
(optional) A named list, passed to |
save_args |
A logical input that defines whether or not to save the list of function inputs in the returned object. |
verbose |
A logical variable that defines whether or not to print messages to the console or to file to relay function progress. If |
con |
If |
progress |
(optional) If the algorithm is implemented step-wise, |
split |
A character string that defines the (approximate) time unit used to split acoustic time series into chunks (e.g., |
cl , varlist |
(optional) Parallelisation options. |
The acoustic-container (AC) algorithm is an approach which uses acoustic detections to infer the possible locations of tagged animals within an area over some time interval. The locational information provided by acoustic detections is represented by acoustic containers, which are areas around receivers that define where an individual could have been at each time point given the spatiotemporal pattern of detections at receivers, a model of detection probability and a movement parameter.
In outline, the crux of the approach is the recognition that acoustic detections typically occur irregularly, but we can consider a sequence of regular time steps between any pair of detections. Each detection anchors our knowledge of the location of an individual around a particular receiver (assuming that all detections are true detections). As time passes between pairs of detections, our uncertainty in the geographical location of an individual expands around the receiver at which the individual was detected before shrinking towards the receiver at which it was next detected. The dynamics of this process are captured by the expansion, contraction and intersection of pairs of acoustic containers.
More specifically, at each time step, we can consider the set of possible locations for the individual from perspective of (a) the receiver at which the individual was detected and (b) the receiver at which the individual is next detected. When an individual is detected, it must be within some radius—say 800 m—of that receiver termed the ‘detection container’. From the perspective of the receiver at which the individual is next detected, the set of possible locations of the individual is wider in line with the time between detections and the movement speed of the animal. The intersection of these two areas defines the set of possible locations for the individual. (In most cases, this is simply that defined by the detection container around the first receiver.) With a more-refined model of detection probability, it may be possible to predict more precisely where the individual is likely to have been within this area. (In situations with depth data, the ACDC algorithm further restricts the set of locations by incorporating information on the animal's depth via depth contours.) Moving forward in time, we can consider a number of regular time steps before the next detection. During this time, from the perspective of the receiver at which the individual was detected, the set of possible locations of the individual expands, because it could have moved further away from the receiver; meanwhile, from the perspective of the receiver at which the individual was next detected, the set of possible locations of the individual shrinks, as the individual must have been located within the detection container of that receiver by the time of the detection. This process is described by the expansion and contraction of ‘acoustic containers’. At each time step, the intersection of the two containers defines the set of possible locations of the individual, possibly weighted by a detection probability (given the lack of detections during this time). These dynamics recognise that as time passes between detections the individual could have moved away from the receiver at which it was last detected but only at a rate and in a direction that fits with the receiver at which the individual was next detected. Thus, when the individual is detected again, our uncertainty about where it could have been collapses to the detection container around the next receiver (and its intersection with the individual's previous (expanded) location and the acoustic container around the following receiver), possibly weighted by a model of detection probability. Throughout this process, the rate of change in container size depends a movement parameter that describes the maximum swimming speed.
This discussion assumes that the timing of detections and intermediate time steps between detections are perfectly aligned. In reality, there is likely to be a mismatch between the timing of detections and the intermediate time steps between detections, which may be poorly approximated the constant expansion and contraction of acoustic containers. The simplest solution to this issue is to round the acoustic time steps to the resolution of the intermediate time steps (specified by step
). This results in a small loss of precision, but assuming that step
is relatively small, the effect should be negligible. In any case, clocks on different receivers are unlikely to be perfectly synced throughout a study. This solution is also computationally preferable to an alternative approach in which the expansion and contraction of containers varies through time, depending on the gaps between observations and other time-specific variables such as behavioural state. However, the latter approach may be implemented in due course.
The end result is a map that shows the expected time spent in different parts of a study area. The main limitation of this approach is the simple treatment of movement, but particle filtering can be used to extent this approach via the incorporate a movement model (see pf
).
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.
Edward Lavender
This function calls .acs_pl
and .acs
to implement the AC algorithm. 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. acdc_simplify
simplifies the outputs and acdc_plot_trace
, acdc_plot_record
and acdc_animate_record
visualise the results. The AC algorithm can be extended to incorporate depth contours via acdc
. Particle filtering can be used to reconstruct movement path via pf
.
#### Step (1) Implement setup_acdc_*() steps
# ... Define detection containers required for AC algorithm (see setup_acdc_containers())
#### Step (2) Prepare movement time series for algorithm
# Focus on an example individual for speed
id <- 25
acc <- dat_acoustics[dat_acoustics$individual_id == id, ][1:25, ]
# Process time series (if necessary)
# ... Observations should be processed to the nearest time step
# ... Duplicate detections should be dropped
#### Example (1) Implement AC algorithm with default arguments
# This implements the algorithm on a single core, printing messages
# ... to the console to monitor function progress.
out_ac <- ac(
acoustics = acc,
step = 120,
bathy = dat_gebco,
detection_containers = dat_containers,
mobility = 200
)
#### Subsequent examples follow the implementation given in acdc().
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.