patter: particle algorithms for animal movement

patter provides particle filtering, smoothing and sampling algorithms for animal movement modelling, with a focus on passive acoustic telemetry systems. This wraps and enhances a fast Julia backend (Patter.jl). The methodology enables the reconstruction of movement paths and patterns of space use. patter unifies a suite of methods formerly known as the flapper algorithms and supersedes the experimental flapper package (Lavender et al., 2023).

Vignettes

For an introduction to patter, use:

• vignette("a-methodology", package = "patter") for a conceptual introduction to the methodology;

• vignette("b-workflow-outline", package = "patter") for an overview of the workflow;

For a full list of all functions, see help(package = 'patter').

For a glossary of key arguments, see glossary.

Datasets

For example datasets from the Movement Ecology of Flapper Skate project (datasets-mefs), which inspired patter, see:

• dat_moorings for acoustic receiver deployments;

• dat_detections for acoustic detection time series;

• dat_archival for archival (depth) time series;

• dat_gebco() for a bathymetry grid;

• dat_coast() for a coastline vector;

• dat_mpa() for a Marine Protected Area boundary

To validate new datasets for use with patter, see pat_setup_data() and/or the assemble_*() function documentation.

For example algorithm outputs (datasets-algorithms), see:

• dat_path() for an example output from sim_path_walk();

• dat_coa() for an example output from coa();

• dat_pff() and dat_pfb() for an example output from pf_filter();

• dat_tff() for an example output from pf_smoother_two_filter();

Set up Julia

To link patter and the Patter.jl Julia backend, use:

• julia_connect() to connect to R to Julia;

• julia_validate() to validate the R—Julia connection;

• set_seed() to set the seed in R and Julia;

• set_map() to make a terra::SpatRaster of the study area available in Julia;

These functions should be run at the start of every R session.

Abstract Types

patter is based on three Abstract Types, defined in Julia:

• State structures hold the state (location) of an animal at a given time step;

• ModelMove structures hold movement model, used to simulate new states;

• ModelObs structures hold observation model parameters, used to evaluate the correspondence between simulated states and observations;

Simulation

To simulate animal movement time series, see:

• sim_path_walk() to simulate a movement path from a walk model (via ModelMove);

• sim_array() to simulate an acoustic array;

• sim_observations() to simulate observational time series (via ModelObs);

To evaluate model skill in reconstructing simulated patterns, see skill_*() functions:

• skill_mb() to calculate mean bias;

• skill_me() to calculate mean error;

• skill_rmse() to calculate root mean squared error;

• skill_R() to calculate Spearman's rank correlation coefficient;

• skill_d() to calculate the index of agreement;

Data exploration

For help with data acquisition, processing, checking and preliminary analyses, see the flapper package. This facilitates:

• Data preparation;

• Spatial operations;

• Distance calculations;

• Movement analyses;

Please submit a feature request if you would like functions from flapper in patter.

Algorithms

The main thrust of patter is the provision of fast, integrated modelling workflow based on particle filtering for reconstructing animal movement paths and emergent patterns of space use from observational time series (with a focus on passive acoustic telemetry systems).

To assemble datasets for particle filtering, use assemble_*() functions:

• assemble_timeline() assembles a timeline;

• assemble_acoustics() assembles an acoustic time series;

• assemble_acoustics_containers() assembles a corresponding time series of acoustic containers;

• assemble_archival() assembles an archival time series;

• assemble_custom() assembles custom time series;

Ancillary time series should be structured in the same way for inclusion in the particle filter.

To implement particle filtering (PF) routines, use:

• pf_filter() to implement the particle filter;

• pf_smoother_two_filter() to implement the two-filter smoother;

These functions return pf_particles objects.

For convenience plotting functions, see:

• plot_xyt() to plot particle locations;

For mapping utilisation distributions, use:

• map_pou() to map probability-of-use;

• map_dens() to create smooth maps using spatstat, plus the supporting functions:

  • as.im.SpatRaster(), to convert SpatRasters to pixel images;

  • as.owin.SpatRaster(), to convert SpatRasters to observation windows;

  • as.owin.sf(), to convert sf objects to observation windows;

• map_hr_*() to map home ranges, specifically:

  • map_hr_prop() for a custom range;

  • map_hr_core() for the 'core' range;

  • map_hr_home() for the 'home' range;

  • map_hr_full() for the full range;

Options

For additional options in patter, see:

• patter-progress to monitor function progress;

Miscellaneous

• See cl_lapply() for R parallelisation;

• See example_setup() for functions used to streamline examples;

• See file_*() functions (e.g., file_list()) for system file helpers;

References

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.

See also

• For information on the flapper algorithms, see Lavender et al. (2023).

• For information on patter's predecessor, see https://github.com/edwardlavender/flapper.

• For further information on patter, including useful resources, see https://github.com/edwardlavender/patter.

• For support, feature requests and bug reports, raise an issue at https://github.com/edwardlavender/patter/issues.

• For the Julia backend, see https://edwardlavender.github.io/Patter.jl.

Author

Edward Lavender (ORCID)