flapper

Routines for the analysis of passive acoustic telemetry data, including the reconstruction of fine-scale movement paths and emergent patterns of space use. https://edwardlavender.github.io/flapper/

Project Status: Active – The project has reached a stable, usable state and is being actively developed. CRAN_Status_Badge

flapper is an R package which provides tools for passive acoustic telemetry data. The package has been particularly motivated by the collection of acoustic and archival data from a Critically Endangered elasmobranch, the flapper skate (Dipturus intermedius), off the west coast of Scotland where a static passive acoustic telemetry array was established to examine the movements of individuals within a Marine Protected Area. flapper has been designed to complement existing packages for the analysis of these data (e.g. VTrack, glatos and fishtrack3d and actel), with a particular focus on the provision of movement modelling methods for passive acoustic telemetry systems that permit the reconstruction of fine-scale movement paths and emergent patterns of space use. To this end, flapper contains functions in the following themes:

  • Data processing tools, including data assembly (e.g., range-testing datasets), the evaluation of false detections and quality checks;
  • Spatial tools, including common spatial operations for the manipulation of spatial data, such as polygon inversion;
  • Distance calculations, including the calculation of distances between receivers, along 3-dimensional movement paths, and of the shortest paths over a surface;
  • Detection statistics, including metrics of sampling effort, such as detection area; and individual detection metrics, such as detection days and co-occurrence;
  • Modelling methods, including a straightforward implementation of the mean-position algorithm for the estimation of centres of activity and new algorithms designed for improved estimates of space use and the reconstruction of movement paths;
  • Simulation tools, including tools for the simulation of passive acoustic telemetry arrays, movement paths, detections and the comparison of simulated and reconstructed patterns of space use under different conditions;

flapper: An R package of routines for the analysis of passive acoustic telemetry data, especially the reconstruction of fine-scale movement paths and emergent patterns of space use. Inserted sample depth and acoustic time series were collected as part of the Movement Ecology of Flapper Skate project by Marine Scotland Science and NatureScot. The insert of the flapper skate is also courtesy of this project. The bathymetry data are sourced from the Ireland, Northern Island and Scotland Hydrographic survey (Howe et al., 2014). Plots were produced using the prettyGraphics package.

For full package details, vignettes and illustrated examples, go to https://edwardlavender.github.io/flapper/.

Highlights

The main highlights of the package are the provision of routines for the rapid calculation of biologically meaningful distances in areas with complex barriers to movement (e.g., coastline) alongside algorithms (most of which are exclusive to flapper) for reconstructing movements and patterns of space use from discrete detections at receivers, especially:

  • lcp_*(). These functions facilitate the calculation of shortest paths and their distances between and around points using efficient C++ algorithms from the cppRouting package. This makes it easy to use biologically meaningful distances (that account for the bathymetric surface over which a benthic animal must move, if applicable, and barriers to movement) in movement models.
  • coa(). This function implements the arithmetic version of the mean-position algorithm to estimate centres of activity (COAs) from discrete detections at receivers, given a detection matrix and the locations of receivers.
  • ac(). The function implements the acoustic-container (AC) algorithm. This is a new approach which utilises the information provided by acoustic detections in the form of acoustic containers to reconstruct the expected time spent in different parts of a study area over the period of observations. Key innovations of this approach include the natural incorporation of barriers to movement (such as coastline), detection probability and information provided by the gaps between detections.
  • dc(). This function implements the ‘depth-contour’ (DC) algorithm. This relates one-dimensional depth time series to a two-dimensional bathymetry surface to determine the extent to which different parts of an area might have (or have not) been used, or effectively represent occupied depths, over time.
  • acdc(). This function implements the ‘acoustic-container depth-contour’ (ACDC) algorithm. This integrates the locational information provided by acoustic detections and concurrent depth observations to refine expectations of the time spent in different parts of a study area over the period of observations.
  • pf() is a particle filtering routine that refines time-specific maps of the possible locations of an animal (from ac(), dc() or acdc()) via a particle simulation and filtering process that permits the reconstruction of movement paths over landscape.
  • sim_*(). These functions provide flexible, joined-up routines for the simulation of receiver arrays, movement paths and detections.

Installation

This package requires R version ≥ 4.0. You can check your current version with R.version.string. Subsequent installation steps (may) require the devtools and pkgbuild packages, which can be installed with install.packages(c("devtools", "pkgbuild")). On Windows, package building requires Rtools. You can check whether Rtools is installed with pkgbuild::has_rtools(). If Rtools is not installed, it is necessary to download and install the appropriate version of Rtools before proceeding by following the instructions here.

Four packages (prettyGraphics, Tools4ETS, fasterRaster and glatos) are required or suggested from GitHub repositories (since they are not currently available from CRAN). These can be installed during the installation process (see below), but it is safer to install them sequentially as follows:

devtools::install_github("edwardlavender/prettyGraphics") # required
devtools::install_github("edwardlavender/Tools4ETS")      # required
devtools::install_github("adamlilith/fasterRaster")       # suggested
devtools::install_github("ocean-tracking-network/glatos") # suggested

To install these packages with their vignettes, add dependencies = TRUE and build_vignettes = TRUE as arguments to the code above (see ?devtools::install_github or ?devtools::install_url for further information). Then, you can install the development version of flapper from GitHub as shown below:

devtools::install_github("edwardlavender/flapper", dependencies = TRUE, build_vignettes = TRUE)

The dependencies = TRUE argument will also install any suggested packages, which are required by some functions/examples and to build vignettes (which will be added to the package in due course). To access the vignettes, use vignette("flapper_intro", package = "flapper") for a general introduction to the package. Note that vignettes have not yet been added to the package.

Example datasets

A key feature of the flapper package is that most functions are designed to be implemented using standard object types (e.g., dataframes and matrices) rather than package-specific object classes. For simplicity, flapper makes some assumptions about variable names that follow a consistent and logical structure (e.g., individual IDs are given as individual_id and receiver IDs are given as receiver_id) but, notwithstanding this framework, this structure means that the functions in the package are accessible and straightforward to use.

Functions are illustrated using simulated data and the following sample data collected from flapper skate off the west coast of Scotland:

  • dat_ids is a dataset containing the characteristics of a sample of tagged flapper skate;
  • dat_moorings is a dataset containing some sample passive acoustic telemetry receiver locations and associated information;
  • dat_acoustics is a dataset containing some sample detection time series;
  • dat_archival is a dataset containing some sample depth time series;
  • dat_sentinel is a dataset containing some sample transmission–detection time series assembled from sentinel tags;

These example datasets were collected by Marine Scotland Science and NatureScot as part of the Movement Ecology of Flapper Skate project and belong to these organisations. If you wish to use these data, please contact Marine Scotland Science and NatureScot for further information.

Data processing tools

A number of functions facilitate the acquisition, assembly, processing and checking of passive acoustic telemetry time series:

  • Data acquisition.
    • query_*() functions query online databases:
      • query_open_topo() queries the Topo Data Application Programming Interface for elevation/bathymetry data;
  • Data assembly.
  • Data processing.
    • process_receiver_id() adds unique receiver IDs to a dataframe (i.e., if the same receiver has been deployed more than once);
    • process_false_detections_sf() passes putative false detections through a spatial filter which incorporates information on receiver locations and animal swimming speeds to interrogate their plausibility;
    • process_quality_check() passes acoustic data through some basic quality checks prior to analysis;
    • process_surface() determines an ‘optimum’ raster aggregation method and error induced by this process;

Spatial tools

A number of functions facilitate spatial operations that support common tasks and modelling algorithms:

  • buffer_and_crop() buffers a spatial object (e.g., receiver locations) and uses this buffered object to crop another (e.g., the local bathymetry);
  • get_intersection() intersects spatial geometries;
  • xy_from_click() gets location coordinates from mouse clicks;
  • crop_from_click() crops a raster to an area defined by mouse clicks;
  • cells_from_val() returns the cells (or a raster of the cells) of a raster that are equal to a specified value or lie within a specified range of values;
  • invert_poly() inverts a polygon (e.g, to define the ‘sea’ from a polygon of the ‘land’);
  • mask_io() masks values in a raster that lie inside or outside of a spatial mask (e.g., to mask the ‘land’ from the ‘sea’);
  • sim_surface() populates a raster with simulated values;
  • split_raster_equally() splits a raster into equal pieces (using code from the greenbrown package);
  • update_extent()shrinks or inflates an extent object;
  • segments_cross_barrier() determines if Euclidean transects cross a barrier;

Distance calculations

Some functions facilitate standard distance calculations using Euclidean distances:

  • dist_btw_clicks() calculates distances and draws segments between sequential mouse clicks on a map;
  • dist_btw_receivers() calculates the Euclidean distances between all combinations of receivers;
  • dist_btw_points_3d() calculates the Euclidean distances between points in three-dimensional space;
  • dist_over_surface() calculates the total Euclidean distance along a path over a three-dimensional surface;

Often, Euclidean distances may not be a suitable representation of distance. This is especially the case for coastal benthic/demersal species in bathymetrically complex environments, for which navigation between locations may require movement over hilly terrain and around coastline. For this reason, a number of functions facilitate the calculation of shortest paths/distances:

  • lcp_costs() calculates the distances between connected cells in a raster, accounting for planar (x, y, diagonal) and vertical (z) distances;
  • lcp_graph_surface() constructs connected graphs for least-cost paths analysis;
  • lcp_from_point() calculates least-cost distances from a point on a raster to all of the other cells of a raster;
  • lcp_over_surface() calculates shortest path(s) and/or the distances of the shortest path(s) over a surface between origin and destination coordinates;
  • lcp_interp() interpolates paths between sequential locations using least-cost paths analysis;
  • lcp_comp() compares Euclidean and shortest-distance metrics for an area;

Detection statistics

A number of functions facilitate the calculation of detection statistics, including those related to sampling effort and to detections of individuals:

Movement metrics

Building on the analysis of detection time series, some functions (get_mvt_*()) provide movement metrics:

Modelling algorithms

The main thrust of flapper is the implementation of algorithms designed to reconstruct fine-scale movement paths and emergent patterns of space use in passive acoustic telemetry systems.

The centres of activity (COA) algorithm

Centres of activity (COA) are one of the most widely used metrics for the reconstruction of patterns of space use from passive acoustic telemetry data. Several methods have been developed to calculate COAs, but the mean-position algorithm is the commonest. To generate estimates of space use, COAs are usually taken as point estimates from which UDs (typically kernel UDs or KUDs) are estimated. flapper facilitates the implementation of this approach with the following functions:

The flapper family of algorithms

Alongside the COA algorithm, this package introduces the flapper of algorithms for the inferring patterns of space use.

The ‘flapper’ family of algorithms. The acoustic-container (AC) branch utilises acoustic data (and/or ancillary information) to reconstruct the set of possible locations for an individual through time. The particle filtering (PF) branch refines this set via the implementation of a particle simulation and filtering approach for the reconstruction of possible movement paths.

AC/DC branch algorithms

The depth-contour (DC) algorithm

The depth-contour (DC) algorithm is the simplest. Whereas the COA approach only makes use of detections, the DC approach only uses depth observations. Specifically, this algorithm uses observed depths (± some error) to define the subset of possible locations of each individual within a defined area: for pelagic species, tagged individuals must be in an area where the seabed depth is at least as deep as the observed depth; for benthic/demersal species, tagged individuals must be in an area where the seabed depth is close to the observed depth. This is implemented via dc(). The ‘quick’ depth-contour (DCQ) algorithm, implemented via dcq(), uses a modified version of this algorithm for quicker run times.

The acoustic-container* (AC*) algorithm(s)

The flapper family-equivalent of the COA algorithm is the acoustic-container (AC) algorithm. This approach represents the information from acoustic detections in the form of acoustic containers, which contract and expand in line with our uncertainty in an individual’s location when it is detected and in the gaps between detections. The acoustic-container depth-contour (ACDC) algorithm combines the AC and DC algorithms, using passive acoustic telemetry data to inform the area within which depth contours are most likely to be found. These algorithms are implemented with the ac*() family of functions:

AC/DC post-processing and analysis

The AC-branch functions (ac(), dc() and acdc()) all return objects of class acdc_archive. These can be processed and analysed using several key functions:

Particle filtering branch algorithms

Each algorithm (AC, DC and ACDC) can be extended through incorporation of a movement model to reconstruct movement paths over a surface that are consistent with the observations (and model assumptions). The resultant algorithms are termed the ACPF, DCPF and ACDCPF algorithms. The approach is implemented via a particle simulation and filtering process provided by the pf*() family of functions:

Simulation tools

flapper provides joined-up routines for the simulation of acoustic arrays, movement paths and detections at receivers:

  • sim_array() simulates alternative array designs;
  • sim_path_*() functions simulate discrete-time movement paths, including:
  • sim_detections() simulates detections at receivers arising from movement paths under a diversity of detection probability models;

To evaluate the performance of alternative algorithms for reconstructing patterns of space use under different array designs, movement models and detections models, eval_by_kud() compares patterns of space use reconstructed from simulated and estimated movement paths using KUDs.

Parallelisation routines

Parallelisation in flapper is facilitated by the cl_*() function family:

Associated packages

  • prettyGraphics facilitates the production of pretty, publication-quality and interactive visualisations, with a particular focus on time series. This makes it easy to create abacus plots, visualise time series (across factor levels, at different temporal scales and in relation to covariates), bathymetric landscapes and movement pathways in three-dimensions, and detection similarity matrices.
  • Tools4ETS provides a set of general tools for ecological time series, including for the definition of time categories, matching time series (e.g., detection observations with temporally varying environmental covariates), flagging independent time series and simulations.
  • fvcom.tbx provides tools for the integration of hydrodynamic model predictions (from the Finite Volume Coastal Ocean Model) with ecological datasets (e.g., detection time series). This facilitates the inclusion of hydrodynamic model predictions as covariates in movement models and the validation of hydrodynamic model predictions with movement datasets or data collected from static acoustic receivers. This package was particularly motivated by the West Scotland Coastal Ocean Modelling System (WeStCOMS).

References

Howe, J. A. et al. (2014). The seabed geomorphology and geological structure of the Firth of Lorn, western Scotland, UK, as revealed by multibeam echo-sounder survey. Earth Environ. Sci. Trans. R. Soc. Edinburgh 105, 273–284. https://doi.org/10.1017/S1755691015000146

Citation

Lavender, E. et al. (2023). An integrative modelling framework for passive acoustic telemetry. Methods in Ecology and Evolution. https://doi.org/10.1111/2041-210X.14193