detection_events: Classify discrete events in detection data

In jsta/glatos: A package for the Great Lakes Acoustic Telemetry Observation System

Classify discrete events in detection data

Description

Reduce detection data into discrete detection events, defined by movement between receivers (or receiver groups, depending on location), or sequential detections at the same location that are separated by a user-defined threshold period of time.

Usage

detection_events(det, location_col = "glatos_array", time_sep = Inf,
  condense = TRUE)

Arguments

det	A glatos_detections object (e.g., produced by read_glatos_detections). OR a data frame containing detection data with four columns described below and one column containing a location grouping variable, whose name is specified by location_col (see below). The following four columns must appear in det: animal_id Individual animal identifier; character. detection_timestamp_utc Detection timestamps; MUST be of class POSIXct. deploy_lat Latitude of receiver deployment in decimal degrees, NAD83. deploy_long Longitude of receiver deployment in decimal degrees, NAD83.
location_col	A character string indicating the column name in det that will be used as the location grouping variable (e.g. "glatos_array"), in quotes.
time_sep	Amount of time (in seconds) that must pass between sequential detections on the same receiver (or group of receivers, depending on specified location) before that detection is considered to belong to a new detection event. The default value Inf, will not define events based on elapsed time (only when location changes).
condense	A logical indicating if the result should be a condensed data frame (condense = TRUE; default value) with one event per row, or the input data frame with new event data columns added condense = TRUE.

Details

mean_latitude and mean_longitude columns in the output dataframe are the mean GPS locations for the detections comprising that detection event. For example, if the a fish was detected at 3 receiver stations in a glatos_array and glatos_array was selected as the location, then GPS location for that event will be the mean of the latitude and longitude for those three receiver stations (weighted based on the number of detections that occurred on each station).

Value

A data.table or tibble object (if input is either type; output class to match input) or data.frame otherwise. Structure depends on value of condense argument:

If condense = TRUE, a data.frame, data.table, or tibble with the following columns:

event	Unique event identifier.
individual	Unique 'animal_id'.
location	Unique 'location'.
mean_latitude	Mean latitude of detections comprising each event.
mean_longitude	Mean longitude of detections comprising each event.
first_detection	The time of the first detection in a given detection event.
last_detection	The time of the last detection in a given detection event.
num_detections	The total number of detection that comprised a given detection event.
res_time_sec	The elapsed time in seconds between the first and last detection in a given event.

If condense = FALSE, a data.frame, data.table, or tibble matching the input data frame det with the following columns added:

time_diff	Lagged time difference in seconds between successive detections of each animal_id.
arrive	Flag (0 or 1) representing the first detection in each event.
depart	Flag (0 or 1) representing the last detection in each event.
event	Integer representing the event number.

Author(s)

T. R. Binder, T. A. Hayden, C. M. Holbrook

Examples

#get path to example detection file
det_file <- system.file("extdata", "walleye_detections.csv",
                         package = "glatos")
det <- read_glatos_detections(det_file)

filt0 <- detection_events(det) #no time filter

#7-day filter
filt_7d <- detection_events(det , time_sep = 604800) 

#7-day filter but return do not condense result
filt_7d <- detection_events(det , time_sep = 604800, condense = FALSE) 

jsta/glatos documentation built on July 11, 2022, 7:01 a.m.