Modelling lake trout movements in Lake Champlain, North America

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, supporting our analyses of lake trout (Salvelinus namaycush) movements in the Lake Champlain passive acoustic telemetry system (North America). This work builds on Futia et al.’s (2024) heuristic analysis of regional residency patterns. We use a state-space model approach. We perform model-based inference using particle algorithms via the patter R and Patter.jl Julia packages.

The key elements of the workflow are as follows:

1. State-space model formulation.
   • Formulate a movement model for lake trout;
   • Formulate an acoustic observation model for Lake Champlain;
2. Simulation analyses.
   • Simulate trajectories using the lake trout movement model;
   • Simulate observations arising from trajectories using the Lake Champlain acoustic observation model;
   • Examine the performance and sensitivity of particle algorithms applied to simulated observations;
3. Real-world analyses.
   • Analyse real-world time series using particle algorithms;

Description

Dependencies

The project was built in R (version 4.5.x) in RStudio and implements local dependency management using renv. This can be used to regenerate the local project library (see Instructions).

Directories

The main elements of the project structure are as follows:

1. bin/ contains bash scripts (for code deployment on a server).

2. data-raw/ contains raw datasets*. This includes:

   • mfutia/: lake trout datasets;
   • model-move/: supporting movement datasets, used to inform the movement model;
   • model-obs/: supporting range testing datasets, used to inform the acoustic observation model;

3. data/ contains processed datasets, algorithm inputs and outputs, generated by *.R and *.jl scripts*. This includes:

   • input/ include input data for analyses, including:
     • map.tif: a map of the study area;
     • real/: additional inputs for real-world analyses (e.g. processed detection data);
     • sim/: additional inputs for simulation analyses;
   • inst/ contains RStudio Project-management files generated by proj.templates:
     • dependencies.rds: a list of dependencies;
     • session-info.rds: a record of information about the R Session;
     • tree.rds: a record of the project directory tree (as generated by proj.templates::use_template_tree() in dev/01-dev.R, see below);
   • output/ contains outputs from analyses, including:
     • real/: outputs from real-world analyses;
     • sim/: outputs from simulation analyses;
   • supp/ contains supporting datasets, used for model development;

4. dev/ contains project-management scripts.

   • 001-dev.R and 002-clone.R are standard proj.templates scripts:
     • 001-dev.R records project set up and development;
     • 002-clone.R is used to clone the project (see ‘Instructions’);
   • 003-clean.R and 004-rebuild support project maintenance:
     • 003-clean.R cleans and rebuilds the data/ directory;
     • 004-rebuild.R re-runs selected R scripts, populating data/;

5. doc/ contains documents*.

6. fig/ contains figures*.

7. Julia/ is the Julia project directory. This includes:

   • sim-data.jl simulates trajectories and observations;
   • run-filter.jl runs the particle filter to evaluate convergence;
   • run-algorithms.jl runs the particle algorithms;

8. R/ contains R scripts:

   • setup-data-map.R defines a map of the study area;
   • setup-data-detection.R processes detection data;
   • setup-data-move-*.R processes movement (e.g., accelerometer) datasets, used to develop the movement model;
   • setup-data-detection-pr-*.R processes detection probability data, used to inform the acoustic observation model;
   • develop-model-move-*.R analyses movement datasets and develops the movement model;
   • develop-model-detection-pr-*.R analyses detection probability datasets and develops the acoustic observation model;
   • develop-model.R collates state-space model parameters;
   • sim-data.R simulates trajectories and observations;
   • explore-data.R explores datasets;
   • run-heuristic.R runs a heuristic algorithm;
   • prepare-analysis.R prepares iteration data.tables and directories for simulation/real-world analyses using patter;
   • (deprecated) trial-patter*.R explored the use of patter to analyse simulation/real-world datasets;
   • (deprecated) plan-patter.R supported the development of an implementation strategy;
   • monitor-patter.R monitors algorithm progress;
   • synthesise-patter.R collates patter outputs;
   • analysis-patter-*.R analyse outputs;
   • refine-patter.R interactively examines convergence failures;
   • exports.R exports selected datasets for related projects;

9. renv/ implements local dependency management for R.

10. src/ contains R source code.

These directories are not currently available in the online version of this repository*.

Instructions

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

1. Clone the project via GitHub.

2. Setup project, following the instructions in dev/002-clone.R:

   • Packages. Work through dev/002-clone.R to use renv to regenerate the local project library. Packages can also be manually reinstalled via 002-clone.R, if required.
   • Directories. Rebuild the project directory tree, via proj.templates::use_template_tree().

3. Source data-raw/ from the sources provided or the authors.

4. Run scripts to reproduce the analyses:

   • Run setup-, develop-, sim- and explore- .R scripts to set up the project;
   • Using tmux or similar, execute 001-workflow.sh to perform inference via run-algorithms.jl;
   • Monitor algorithm process via monitor-patter.R;
   • Synthesise and analyse outputs via synthesise-* and analyse-* .R scripts;

Citations

Lavender, E. et al. (in prep). Big data analysis of animal movements in aquatic ecosystems with acoustic telemetry.

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.

---