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.
Arguments
- det
A
glatos_detectionsobject (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_idIndividual animal identifier; character.
detection_timestamp_utcDetection timestamps; MUST be of class POSIXct.
deploy_latLatitude of receiver deployment in decimal degrees, NAD83.
deploy_longLongitude of receiver deployment in decimal degrees, NAD83.
- location_col
A character string indicating the column name in
detthat 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 addedcondense = TRUE.
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.
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).
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
#> The event filter distilled 7180 detections down to 165 distinct detection events.
# 7-day filter
filt_7d <- detection_events(det, time_sep = 604800)
#> The event filter distilled 7180 detections down to 171 distinct detection events.
# 7-day filter but return do not condense result
filt_7d <- detection_events(det, time_sep = 604800, condense = FALSE)
#> The event filter identified 171 distinct events in 7180 detections.