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/
Warning The
flapperpackage has been superseeded bypatter, which is simpler, faster and better tested.patterwill be made available late 2023. Please get in touch to support beta testing.
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. Earth Environ. Sci. Trans. R. Soc. Edinburgh 105, 273–284.). Plots
were produced using the
prettyGraphics
package.
For full package details, vignettes and illustrated examples, go to https://edwardlavender.github.io/flapper/.
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 efficientC++algorithms from thecppRoutingpackage. 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 (fromac(),dc()oracdc()) 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.
Warning The
flapperpackage has been superseeded bypatter, which is simpler, faster and better tested.patterwill be made available late 2023. Please get in touch to support beta testing.
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.
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_idsis a dataset containing the characteristics of a sample of tagged flapper skate;dat_mooringsis a dataset containing some sample passive acoustic telemetry receiver locations and associated information;dat_acousticsis a dataset containing some sample detection time series;dat_archivalis a dataset containing some sample depth time series;dat_sentinelis 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.
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.
assemble_sentinel_counts()assembles counts of transmissions/detections from sentinel tags for modelling purposes (i.e., to model detection probability);make_matrix_*()functions create matrices of individual and receiver deployment time series and detection time series:make_matrix_ids()matricises individual deployment time series;make_matrix_receivers()matricises receiver deployment time series;make_matrix_detections()matricises detection time series;
make_df_*()functions (i.e.,make_df_detections()) reverse this process;
- 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;
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;
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;
A number of functions facilitate the calculation of detection statistics, including those related to sampling effort and to detections of individuals:
get_detection_pr()calculates detection probability given a model for detection probability with distance;get_detection_containers()defines detection containers (areas within the maximum detection range) around receivers;get_detection_containers_overlap()identifies receivers with overlapping detection containers in space and time;get_detection_containers_envir()extracts environmental conditions from within receiver detection ranges, accounting for detection probability;get_detection_area_sum()calculates the total area surveyed by receivers;get_detection_area_ts()defines a time series of the area surveyed by receivers;get_n_operational_ts()defines a time series of the number of operational units (e.g., individuals at liberty or active receivers)get_id_rec_overlap()calculates the overlap between the deployment periods of tagged individuals and receivers;get_detection_days()calculates the total number of days during which each individual was detected (termed ‘detection days’);get_detection_clumps()identifies detection ‘clumps’ and calculates their lengths;get_detection_overlaps()identifies ‘overlapping’ detections;get_residents()identifies ‘resident’ individuals;make_matrix_cooccurence()computes a detection history similarity matrix across individuals;
Building on the analysis of detection time series, some functions
(get_mvt_*()) provide movement metrics:
get_mvt_mobility_*()functions estimate swimming speeds:get_mvt_mobility_from_acoustics()estimates swimming speeds from acoustic detections;get_mvt_mobility_from_archival()estimates swimming speeds from archival time series;
get_mvt_resting()identifies ‘resting’ behaviour from archival time series;get_hr_*()functions get animal ‘home ranges’:get_hr_prop()gets a custom range from a utilisation distribution (UD);get_hr_core()gets the ‘core range’ from a UD;get_hr_home()gets the ‘home range’ from a UD;get_hr_full()gets the ‘full range’ from a UD;
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.
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:
coa_setup_delta_t()informs decisions as to an appropriate time interval over which to calculate COAs;make_matrix_detections()summarises detections over time intervals (see above);coa()implements the arithmetic version of the mean-position algorithm to calculate COAs;kud_habitat(),kud_around_coastline()andkud_around_coastline_fast()facilitate the estimation of home ranges (e.g., from estimated COAs) in areas of complex coastline;
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.
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 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:
acs_setup_mobility()examines the assumption of a constant ‘mobility’ parameter;acs_setup_containers()defines the detection containers for the algorithm(s);acs_setup_detection_kernels()defines detection probability kernels for the algorithm(s);ac()andacdc()implement the algorithm(s), via the back-end functions.acs_pl()and.acs();
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:
acdc_simplify()simplifiesacdc_archive-classobjects intoacdc_record-classobjects;acdc_access_*()functions provide short-cuts to different elements ofacdc_record-classobjects:acdc_access_dat()accesses stored dataframes;acdc_access_timesteps()accesses the total number of time steps;acdc_access_maps()accesses stored maps;
acdc_plot_trace()plots acoustic container dynamics;acdc_plot_record()plots the results of the algorithm(s);acdc_animate_record()creates html animations of algorithm(s);
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:
pf_setup_movement_prprovides a simple movement model that defines the probability of movement between locations given the distance between them;pf_setup_record()creates an ordered list of input files;pf_setup_optimisers()controls optimisation settings;pf()implements the particle filtering routine;pf_access_history_files()lists particle histories saved to file;pf_access_history()accesses particle histories;pf_access_particles_unique()accesses unique particle samples;pf_plot_history()plots particle histories;pf_animate_history()animates particle histories;pf_simplify()processes particle histories and assembles movement paths;pf_plot_map()maps the expected ‘proportion-of-use’ (POU) across an area based on sampled particles or reconstructed paths;pf_kud()smooths POU maps using kernel smoothing;pf_kud_1()andpf_kud_2()apply kernel smoothing to sampled particles or reconstructed paths;pf_loglik()calculates the log-probability of reconstructed paths, given the movement model;pf_plot_1d()plots the depth time series from observed and reconstructed paths;pf_plot_2d()maps the reconstructed paths in two-dimensions;pf_plot_3d()maps the reconstructed paths in three-dimensions;
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_path_sa(), supported bysim_steps()andsim_angles(), simulates movement paths (possibly in restricted areas) from step lengths and turning angles;sim_path_ou_1()simulates movement paths under Ornstein-Uhlenbeck processes;
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 in
flapper is facilitated by
the cl_*() function family:
cl_lapply()is a wrapper forpbapply::pblapply()that handles cluster checking set up and closure, using the following functions:cl_check()checks a cluster;cl_cores()identifies the number of cores;cl_chunks()defines chunks for parallelisation;cl_export()exports objects required by a cluster;cl_stop()closes a cluster;
For an overview of the flapper algorithms, see: Lavender, E., Biber, S., Illian, J., James, M., Wright, P. J., Thorburn, J., & Smout, S. (2023). An integrative modelling framework for passive acoustic telemetry. Methods in Ecology and Evolution, 00, 1–13. https://doi.org/10.1111/2041-210X.14193
For further code examples, see:
flapper_demofor a demo of the flapper algorithms;flapper_simfor simulation-based explorations of the algorithms;flapper_applfor example real-world applications;
For further information of the flapper package, see:
?flapper::flapperfor an overview of package functions;?flapper::acfor information on specific functions (e.g.,ac(), which implements the acoustic-container algorithm);
flapper is a new,
proof-of-concept R package. It was written
to support the implementation of a novel, mathematical framework for
movement modelling in passive acoustic telemetry systems in our study
system in Scotland. The functions are extensively documented but the
package is at an early stage of evolution. All routines are
experimental. Researchers interested in using the package are encouraged
to get in touch while the methods and package remain at an early stage
of evolution ([email protected]).
- 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).
To cite package flapper
in publications, please use Lavender et al. (2023). For residency
analyses, please also cite Lavender et al. (2021).
Lavender, E. et al. (2021). Movement patterns of a Critically Endangered elasmobranch (Dipturus intermedius) in a Marine Protected Area. Aquatic Conservation: Marine and Freshwater Ecosystems, 32, 348–365. https://doi.org/10.1002/aqc.3753
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
For the shortest-path routines, please also consider citing
cppRouting:
Larmet V (2022). cppRouting: Algorithms for Routing and Solving the Traffic Assignment Problem. R package version 3.1. https://CRAN.R-project.org/package=cppRouting.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent