flapper: Routines for the analysis of passive acoustic telemetry data

flapper is an R package that provides routines for the analysis of passive acoustic telemetry data, including for data processing, description (via detection statistics and movement metrics), modelling and simulation. These routines are supported by a series of helper functions (including distance calculators, spatial tools and parallelisation options). The main contribution is the provision of a family of algorithms for movement modelling in passive acoustic telemetry systems that permits the reconstruction of fine-scale movement paths and emergent patterns of space use. Package development has been motivated by passive acoustic telemetry data from a Critically Endangered benthic elasmobranch (the flapper skate, Dipturus intermedius) off the west coast of Scotland.

Data processing

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

• Data acquisition

  • 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_ids matricises individual deployment time series;

  • make_matrix_receivers matricises receiver deployment time series;

  • make_matrix_detections matricises detection time series;

  • make_df_detections reverses this process;

• Data processing

  • process_receiver_id adds unique receiver IDs to a dataframe (e.g., if the same receiver has been deployed more than once);

  • process_false_detections_sf passes putative false detections through a spatial filter which incorporates ancillary 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

Some 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 (http://greenbrown.r-forge.r-project.org) package);

• update_extent shrinks or inflates an extent object;

• segments_cross_barrier determines if Euclidean transects cross a barrier;

Distance calculations

Some functions facilitate distance calculations, including the calculation of distances between receivers, along 3-dimensional movement paths, and of the shortest paths over a surface.

• 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 Euclidean distance along a path over a three-dimensional surface;

• Shortest (least-cost) 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 the 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

Some 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 on 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;

Movement metrics

Building on the analysis of detection time series, some functions 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;

Modelling algorithms

The main thrust of flapper is the implementation of existing and new 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

  • coa_setup_delta_t informs decisions as to an appropriate time interval over which to calculate COAs;

  • make_matrix_detections summarises matrices over time intervals (see above);

  • coa implements the arithmetic version of the mean-position algorithm to calculate COAs;

  • kud_habitat, kud_around_coastline and kud_around_coastline_fast facilitate the estimation of home ranges (e.g., from estimated COAs) in areas of complex coastline;

• The `flapper` family of algorithms

  • The AC/DC branch

    • The depth-contour (DC) algorithm

      • dc implements the DC algorithm;

      • dcq implements the quick DC (DCQ) algorithm;

    • The acoustic-container* (AC*) algorithms

      • 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 and acdc implement the acoustic-container (AC) and acoustic-container depth-contour (ACDC) algorithms, via .acs_pl and .acs;

    • AC/DC processing

      • acdc_simplify simplifies acdc_archive-class objects into acdc_record-class objects;

      • acdc_access functions provide short-cuts to different elements of acdc_record-class objects:

      • acdc_access_dat accesses stored dataframes in an acdc_record-class object object;

      • acdc_access_timesteps accesses the total number of time steps in an acdc_record-class object;

      • acdc_access_maps accesses stored maps in an acdc_record-class object;

      • acdc_plot_trace plots acoustic container dynamics;

      • acdc_plot_record plots the results of the algorithm(s);

      • acdc_animate_record creates html animations of the algorithm(s);

  • The particle filtering branch

    • pf_setup_movement_pr provides 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 PF routine, building on the AC, DC and ACDC algorithms to form the ACPF, DCPF and ACDCPF algorithms;

    • 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 assembles movement paths from particle histories;

    • pf_plot_map maps the `proportion-of =use' across an area based on sampled particles or reconstructed paths;

    • pf_kud smooths POU maps using kernel smoothing;

    • pf_kud_1 and pf_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;

Simulations

A set of sim_*() functions provide an integrated workflow for the simulation of receiver arrays, movement paths and detections under different array designs, movement models and detection models:

• sim_array simulates alternative array designs;

• sim_path_* functions simulate discrete-time movement paths, including:

  • sim_path_sa, supported by sim_steps and sim_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;

Another set of functions facilitate the evaluation of the performance of alternative algorithms for inferring patterns of space use under different array designs, movement models and detections models:

• eval_by_kud compares patterns of space use inferred from simulated and estimated movement paths using kernel utilisation distributions;

Parallelisation

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

• cl_lapply is a wrapper for pblapply that handles cluster checking set up and closure (see flapper-tips-parallel) 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;

See also

https://github.com/edwardlavender/flapper

Author

Edward Lavender