Workflow outline

This vignette lists the steps required to use patter to reconstruct movements and patterns of space use. Use it as a reference. See package documentation, such as the README, for streamlined example workflow(s). See the patter-flapper project for a complete, real-world analysis.

Set up

1. Load the patter package via library(patter).

2. Connect to Julia via julia_connect().

3. Set the seed in R and Julia via set_seed().

Preparation

Prepare study area

1. Define a terra::SpatRaster map of the study area:

   • In our applications, the map is a bathymetry SpatRaster (see ?dat_gebco and ?glossary);
   • Mask inhospitable habitats (e.g., land) using NAs;
   • Export the map to Julia via set_map();

Prepare movement model

1. Define the State type:

   • State defines the components of the animal’s movement that you want to track;
   • For example, if you want to track x and y locations, use StateXY;

2. Define a corresponding movement model (ModelMove) instance:

   • The movement model defines the animal’s movement capacity;
   • See ?ModelMove for built-in options and instructions for custom sub-types;

Prepare observations

1. Define observational datasets:

   • patter should be able to work with any kind of observational dataset;
   • See datasets-mefs for example datasets included in the package;

2. Validate datasets:

   • Datasets used in patter require manual preparation for analysis;
   • Example considerations for passive acoustic telemetry data include:
     • False detections (e.g. ?glatos::false_detections());
     • Detection timing;
     • Receiver locations;
   • For passive acoustic telemetry and/or archival data, patter provides a pat_setup_data() function which validates data format of these data types for use in patter;

3. Define observation models (ModelObs) sub-types:

   • Observation models link individual movements to the observations;
   • See ?ModelObs for built-in observation models and instructions for custom sub-types;

4. Collate observations and observation model parameters:

   • Define a timeline of interest;
   • Extract the observations for a particular individual;
   • Observations should be arranged as [data.table::data.table]s in long-format;
   • For passive acoustic telemetry and archival datasets, use pat_setup_data() and assemble_*() functions to assemble datasets as required;
   • Otherwise, see the assemble_*() function documentation for straightforward dataset assembly instructions;

5. To simulate datasets instead, see sim_*() functions;

Particle algorithms

Forward filter

1. Implement the particle filter via pf_filter():
   • This returns a list, which includes a states [data.table::data.table] that defines the possible states (locations) of the individual at each time step (according to the movement model and the observations);

Two-filter smoother

1. Implement the particle filter forwards and backwards;

2. Implement the two-filter smoother via pf_smoother_two_filter():

   • This refines outputs from the filter;

Mapping

1. Plot particle positions via pf_plot_*();

2. Map utilisation distributions:

   • Map probability-of-use via map_pou();
   • Map smoothed probability density via map_dens();

3. Map home ranges via map_hr_*();

---