Skip to contents

Utilities: check data

Source: R/pat_setup_data-internal.R
check_dlist.Rd

These functions validate user datasets. See Details for patter requirements.

Usage

check_map(.map)

check_detections(.detections, .moorings = NULL)

check_moorings(.moorings, .detections = NULL, .map)

check_services(.services, .moorings)

check_archival(.archival)

Arguments

.map

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

.detections, .moorings, .services, .archival

Observation data.table::data.tables.

Value

Each function returns the input dataset, as described, formatted in line with patter's requirements.

Details

These are internal functions that ensure that input dataset(s) meet patter requirements. Users with acoustic and/or archival data should implement pat_setup_data() to prepare datasets for patter functions. Downstream functions (often) silently assume that input datasets meet all requirements, without subsequent checks. This simplifies internal code and documentation.

  • check_map() checks the .map terra::SpatRaster:

    • Class: terra::SpatRaster;

    • Name(s): "map_value";

    • Properties:

      • A square grid is recommended;

      • Absolute values (m) are recommended;

      • A planar grid with coordinates in metres is currently required;

    • Source:

      • The data source may be in memory or on disk, but the former is faster for pure R functions;

  • check_detections() checks detection time series:

    • Class: data.table::data.table;

    • Columns:

      • timestamp—an ordered, POSIXct vector of time stamps with a defined tzone attribute;

      • receiver_id—see .moorings$receiver_id;

    • Properties:

      • Each row defines a detection event;

      • Functions assume accurate clock alignment between receivers;

      • For most functions, a single time series (for one individual) is required;

  • check_services() checks acoustic servicing records:

    • Class: data.table::data.table;

    • Columns:

      • receiver_id—see .moorings$receiver_id;

      • receiver_start, receiver_end—POSIXct vectors of service start and end dates. Before/after service events, receivers are assumed to have been deployed in the same locations; receiver deployments in different locations before/after servicing should be treated as distinct deployments in .moorings.

    • Properties:

      • Serviced receivers should be found in the .moorings dataset;

  • check_moorings() checks receiver deployment records:

    • Class: data.table::data.table;

    • Columns:

      • receiver_id—an integer vector of unique receiver deployments (1, ..., N);

      • receiver_x and receiver_y``---Receiver coordinates on a planar projection, matching .map`;

    • Properties:

      • receiver_start should precede receiver_end;

      • Receiver deployment periods should (usually) at least partially overlap with the time period of acoustic detections;

      • Receiver coordinates must be valid on .map (not currently validated);

  • check_archival() checks archival depth time series data:

    • Class: data.table::data.table;

    • Columns:

      • timestamp—an ordered, POSIXct vector of time stamps with a defined tzone attribute;

      • depth—a numeric vector of (absolute) depths (m);

    • Properties:

      • Functions assume accurate clock alignment between acoustic and archival tags (if applicable);

      • For most functions, a single time series (for one individual) is required;

For all datasets, NAs may cause unexpected errors and produce a message.

NULL inputs are permitted in all check_{data} functions, in which case NULL is returned.

See also

Author

Edward Lavender