patter set up: datasets

This function is used to set up and validate telemetry data for patter functions. Use it if you have acoustic and/or archival data.

Usage

pat_setup_data(
  .map = NULL,
  .detections = NULL,
  .moorings = NULL,
  .services = NULL,
  .archival = NULL
)

Arguments

.map

(optional) A terra::SpatRaster that defines the study area (see glossary).

.detections, .services, .archival, .moorings

(optional) data.table::data.tables of observations and and associated parameters.

• .detections contains a detection time series (see dat_detections for an example);

• .moorings contains receiver deployments (see dat_moorings) for an example);

• .services contains receiver servicing information (times during the deployment period of a receiver when it was not active due to servicing);

• .archival contains archival (depth) time series (see dat_archival for an example);

Value

The function returns a named list with one element for each input argument.

Details

The preparation of datasets for patter is a one-off inconvenience. You should be able to analyse any kind of electronic tagging and tracking data using the main patter functions (such as pf_filter()). For passive acoustic telemetry data and archival (depth) data, patter provides some additional helper routines and functionality (such as data assembly routines for the particle filter). If you have acoustic and/or archival data, use pat_setup_data() to verify that your datasets meet patter requirements and exploit this additional functionality. See the check_dlist documentation for the required properties of each input dataset. All requirements are kept to a minimum and are straightforward to address. To minimise inconvenience, all inputs are optional in pat_setup_data(). For other data types, see the documentation for assemble_*() functions to incorporate them in particle filtering algorithms. Downstream functions may assume that input data are correctly formatted, which streamlines the API, documentation and internal code.

On Linux, this function cannot be used within a Julia session.

Author

Edward Lavender

Examples

if (patter_run(.julia = FALSE, .geospatial = TRUE)) {

  # Setup acoustic and archival data for use with `patter` functions
  dlist <- pat_setup_data(.map = dat_gebco(),
                          .detections = dat_detections,
                          .moorings = dat_moorings,
                          .services = NULL,
                          .archival = dat_archival)

  # `pat_setup_data()` returns a `list` with the updated datasets
  summary(dlist)

  # Extract updated datasets for use in downstream functions
  map <- dlist$map
  detections <- dlist$detections
  moorings   <- dlist$archival
  services   <- dlist$services
  archival   <- dlist$archival

}
#> `.map`: this is a reminder that a planar coordinate reference system (coordinate units: metres) is (currently) required. You can safely ignore this message if this is the case!
#> `.map`: there is a speed penalty for grids that do not exist in memory in some functions.
#> `.detections`: multiple individuals detected in dataset.
#> `.detections`: time stamps should be ordered chronologically.
#> `.archival`: multiple individuals detected in dataset.
#> `.archival`: time stamps should be ordered chronologically.