R/processing.R
process_receiver_id.RdThis function extracts the unique receiver deployment IDs (e.g., 1,...n) from a dataframe containing receiver attributes (e.g. unique receiver deployment IDs, receiver codes and locations), termed moorings, that correspond to passive acoustic telemetry (PAT) receiver codes in detection time series, termed acoustics. This is especially useful if the same receiver has been deployed multiple times (e.g. in different locations) over the course of the study. In this scenario, the receiver code in the PAT detection time series does not uniquely identify the unique receiver deployment, which means that receiver codes in PAT data and metadata cannot simply be matched: instead, both receiver code(s) and the time of detection(s) need to be included in the matching procedure. In this case, process_receiver_id examines each receiver with detections in acoustics. If that receiver was redeployed, the function examines the time of each detection and returns the ID of the receiver that recorded that detection (given the timing of receiver deployment). If each receiver was only deployed once, this function simply matches receiver codes in moorings and receiver codes in acoustics and returns the receiver IDs (which, in this case, may be the same as the receiver codes) in moorings that correspond to each receiver code in acoustics.
process_receiver_id(acoustics, moorings)A dataframe which comprises passive acoustic telemetry detection time series. This must contain two named columns: `timestamp', a POSIXct vector which defines the time of each detection; and `receiver', a vector which defines the receiver at which each detection was made. The column `receiver' should also be found in moorings (see below).
A dataframe which contains passive acoustic telemetry receiver metadata. This must contain four named columns: `receiver', as above for acoustics; `receiver_id', a unique identifier for each receiver deployment; `receiver_start_date', a POSIXct vector which defines the time of each receiver deployment; and `receiver_end_date', a POSIXct vector which defines the end of each receiver deployment. If objects of class Date are provided for `receiver_start_date' and `receiver_end_date', these are coerced to POSIXct objects with a warning so that the timing of receiver detections and deployment is comparable (i.e., of the same object type).
The function returns a vector of receiver IDs, as defined in the moorings$receiver_id column, which correspond to each detection in the acoustics dataframe.
The function implements foverlaps to overlap the timing of detections with the timing of receiver deployments to account for receiver deployment in the assignment of receiver IDs.
add_unit_id is a slightly more general function.
#### Define example data
# In this example, we have two receivers, but one has been re-deployed:
moorings <- data.frame(
receiver = c(1, 1, 2),
receiver_id = c(1, 2, 3),
start_date = as.POSIXct(c(
"2016-01-01",
"2016-01-02",
"2016-01-01"
), tz = "UTC"),
end_date = as.POSIXct(c(
"2016-01-02",
"2016-01-03",
"2016-01-02"
), tz = "UTC")
)
# Our observational dataframe contains receivers but not unique receiver IDs:
acoustics <- data.frame(
receiver = c(1, 1, 2),
timestamp = as.POSIXct(c(
"2016-01-01 00:30:00",
"2016-01-02 00:30:00",
"2016-01-01 00:30:00"
), tz = "UTC")
)
#### Example (1): Add unique receiver IDs to the observational dataframe
# The first observation corresponds to receiver 1;
# The second observation corresponds to the same receiver
# ... but a different deployment, and has receiver_id = 2
# The third observation corresponds to receiver id 3;
acoustics$receiver_id <- process_receiver_id(acoustics, moorings)
acoustics
#> receiver timestamp receiver_id
#> 1 1 2016-01-01 00:30:00 1
#> 2 1 2016-01-02 00:30:00 2
#> 3 2 2016-01-01 00:30:00 3