Movement modelling in receiver networks

Edward Lavender*

^*This repository is maintained by Edward Lavender (edward.lavender@eawag.ch).

Introduction

This repository contains methods, written in R and organised as an RStudio Project, for the evaluation of methods designed to reconstruct movements and/or patterns of space use of tagged animals in passive acoustic telemetry systems. This code supports Lavender, E. et al. (in prep). Using simulated data, we compared the performance of the prevailing heuristic methods (i.e., centres of activity [COAs] and refined shortest paths [RSPs]) alongside our new particle-based methods, implemented by the patter package, for reconstructing patterns of space use. We found that particle-based methods outperform heuristic approaches across the board and represent a new state-of-the-art for movement modelling in passive acoustic telemetry systems.

Key elements of the workflow include:

• Simulation of arrays, movement paths and observations (e.g. detections);
• Implementation of approaches for the reconstruction of patterns of space use;
• Analyses of method performance under different conditions;
• Analyses of method sensitivity under different conditions;

Description

Dependencies

The project was built in R (version 4.3.1) in RStudio and implements local dependency management using renv. This manages the installation of the dv package (from GitHub), as well as other packages from the Comprehensive R Archive Network. The first time the project is opened, renv can be used to regenerate the local project library, as described in renv.lock (via .Rprofile and renv/activate.R).

Directories

The project follows a standardised structure encouraged by the dv package. The high-level structure was generated via dv::use_template_proj(). The contents as follows:

1. renv/ implements local dependency management.

2. data/ contains data files:

   • sims/ contains simulation inputs and outputs:
     • input/ contains simulation inputs;
     • output/ contains simulation outputs;
     • inst/ contains RStudio Project-management files generated by dv:
       • dependencies.rds is a list of dependencies;
       • session-info.rds is a record of information about the R Session;
       • tree.rds is a record of the project directory tree (as generated by dv::use_template_tree() in dev/02-dev.R, see below);
         

3. R/ contains scripts for data processing and analysis:

   • sim-data.R simulates ‘observations’;
   • plot-data.R plots observation models and simulated datasets;
   • process-data.R processes data for algorithm implementations;
   • process-data-rsp.R processes data for RSP implementations;
   • run-performance-path.R estimates utilisation distributions (UDs) for simulated paths;
   • run-performance-coa.R estimates UDs from COAs;
   • run-performance-rsp.R estimates UDs from RSPs;
   • run-patter.R estimates UDs using particle algorithms;
   • calculate-skill.R calculates skill metrics for selected algorithms;
   • analyse-performance.R compares algorithm performance;
   • analyse-sensitivity.R analyses algorithm sensitivity to parameter mis-specification;
     

4. src/ contains helper (R) functions.

5. Julia/ contains a Julia project.

   • This is set up by patter;

6. dev/ contains project-management scripts.

   • 01-dev.R and 02-clone.R are standard dv scripts:
     • 01-dev.R records project set up and development;
     • 02-clone.R is used to clone the project (see ‘Instructions’);

7. fig/ contains figures.

8. doc/ contains supporting documents.

Note that the data/ (except data/inst/), fig/ and doc/ directories are not provided in the online version of this repository. However, all algorithm inputs/outputs can be reproduced by implementing the code, as described below.

Instructions

Follow the steps described below to clone the project and reproduce the workflow.

1. Clone the project via GitHub. Follow the instructions in dev/02-clone.R to install packages and directories:

   • Packages. Work through dev/02-clone.R to use renv to regenerate the local project library. Contact us for support with the installation of custom packages, if required.
   • Directories. Rebuild the project directory tree, via dv::use_template_tree(). This re-creates the folders required to store outputs.

2. Run the scripts in order to simulate data, implement the algorithms and analyse results.

Citation

Lavender, E. et al. (in prep). Particle algorithms for animal movement modelling in autonomous receiver networks.

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

---