process_receiver_id.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/processing.R
\name{process_receiver_id}
\alias{process_receiver_id}
\title{Add unique receiver IDs to passive acoustic telemetry time series}
\usage{
process_receiver_id(acoustics, moorings)
}
\arguments{
\item{acoustics}{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 \code{moorings} (see below).}

\item{moorings}{A dataframe which contains passive acoustic telemetry receiver metadata. This must contain four named columns: `receiver', as above for \code{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).}
}
\value{
The function returns a vector of receiver IDs, as defined in the \code{moorings$receiver_id} column, which correspond to each detection in the \code{acoustics} dataframe.
}
\description{
This 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 \code{moorings}, that correspond to passive acoustic telemetry (PAT) receiver codes in detection time series, termed \code{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, \code{\link[flapper]{process_receiver_id}} examines each receiver with detections in \code{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 \code{moorings} and receiver codes in \code{acoustics} and returns the receiver IDs (which, in this case, may be the same as the receiver codes) in \code{moorings} that correspond to each receiver code in \code{acoustics}.
}
\details{
The function implements \code{\link[data.table]{foverlaps}} to overlap the timing of detections with the timing of receiver deployments to account for receiver deployment in the assignment of receiver IDs.
}
\examples{
#### 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

}
\seealso{
\code{\link[Tools4ETS]{add_unit_id}} is a slightly more general function.
}
\author{
Edward Lavender
}