Update documentation (continued).

R/make_dfs.R

@@ -2,7 +2,7 @@
 #' @description This function converts a matrix of detections (0, 1) by time stamp and receiver into a dataframe.
 #'
 #' @param acoustics A detection matrix (time stamps x receivers) in which the cells define whether (1) or not (0) a detection was made at each time stamp/receiver combination. 'Meaningful' time stamps and receiver IDs can be taken from the row and column names of this matrix, if specified (see \code{set_names}).
-#' @param only_keep_detections A logical variable that defines whether or not to retain only observations that correspond to detections. (If \code{only_keep_detections = FALSE} the returned dataframe includes time stamps without detections.)
+#' @param only_keep_detections A logical variable that defines whether or not to retain only observations that correspond to detections. (If \code{only_keep_detections = FALSE}, the returned dataframe includes time stamps without detections.)
 #' @param set_names A logical variable that defines whether or not to take the row and column names of \code{acoustics} as the time stamps and receiver IDs. (If \code{set_names = FALSE}, time stamps and receiver IDs are simply given as integer vectors of 1 to the number of rows or columns respectively.)
 #' @param as_POSIXct If \code{set_names = TRUE}, \code{as_POSIXct} is a function that converts the row names of \code{acoustics} into POSIXct time stamps.
 #'

R/processing.R

@@ -1,6 +1,6 @@
 ######################################
 ######################################
-#### process_receiver_ids()
+#### process_receiver_id()
 
 #' @title Add unique receiver IDs to passive acoustic telemetry time series
 #' @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}.
@@ -119,12 +119,14 @@ process_receiver_id <-
 #### process_false_detections_sf()
 
 #' @title Pass putative false detections through a spatial filter
-#' @description The identification of false detections in acoustic telemetry data is an important aspect of processing and/or modelling these data. False detections can be identified using the short interval criterion, whereby any detection of an individual at a receiver which is not accompanied by other detections at the same receiver in a specified time window (depending on the nominal acoustic transmission delay) are flagged. This approach can be implemented using the \code{\link[glatos]{false_detections}} function in the \code{\link[glatos]{glatos}} package. Flag detections can then be examined, or passed through other filters, to examine their plausibility. This function passes false detections flagged by \code{\link[glatos]{false_detections}} through a spatial filter. The key idea is that detections at nearby receivers within the define time window can be used to suggest 'false' detections which are, in fact, plausible. To implement this approach, the user must define a dataframe comprising detections, a temporal threshold, a spatial threshold and a dataframe of distances between receivers. The function examines whether any putative false detection are accompanied by additional detections at other receivers within a user-defined Euclidean distance of that receiver. If so, these could be explained by an individual which dips in-and-out of the detection ranges of receivers (e.g. in a sparse acoustic array) and may not, in fact, be false.
+#' @description The identification of false detections in acoustic telemetry data is an important aspect of processing and/or modelling these data. False detections can be identified using the short interval criterion, whereby any detection of an individual at a receiver which is not accompanied by other detections at the same receiver in a specified time window (depending on the nominal acoustic transmission delay) are flagged. This approach can be implemented using the \code{\link[glatos]{false_detections}} function in the \code{\link[glatos]{glatos}} package. Flag detections can then be examined, or passed through other filters, to examine their plausibility.
 #'
-#' @param det A dataframe containing detection data. This should contain the following columns: 'detection_timestamp_utc', 'transmitter_codespace', 'transmitter_id' and 'receiver_sn', as well as 'passed_filter' (see \code{\link[glatos]{false_detections}}).
-#' @param tf A number which defines the time threshold (s) used to flag false detections (see \code{\link[glatos]{false_detections}}).
-#' @param sf A number which defines the threshold Euclidean distance between receivers beyond which, even if a false detection is accompanied by detections at other receivers, it is likely to be a true false detection, because the the individual could not have moved between receivers separated by more than this threshold over the specified time interval. \code{sf} should be defined in the same units as the distances provided in \code{dist} (see below).
-#' @param dist_btw_receivers A dataframe which defines the distances between receiver pairs. This should contain the columns: 'r1', 'r2' and 'dist', whereby 'r1' and 'r2' contain the unique receiver serial number for all combinations of receivers and 'dist' contains the distance between them. This dataframe should include duplicate combinations (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). This can be created with \code{\link[flapper]{dist_btw_receivers}}.
+#' This function passes false detections flagged by \code{\link[glatos]{false_detections}} through a spatial filter. The key idea is that detections at nearby receivers within a defined time window may, in fact, be plausible. To implement this approach, the user must define a dataframe comprising detections, a temporal threshold, a spatial threshold and a dataframe of distances between receivers. The function examines whether any putative false detections are accompanied by additional detections at other receivers within a user-defined time window and Euclidean distance of that receiver. If so, these could be explained by an individual that dips in-and-out of the detection ranges of receivers (e.g. in a sparse acoustic array) and may not, in fact, be false.
+#'
+#' @param det A dataframe containing detection time series. Following \code{\link[glatos]{false_detections}}, this should contain the following columns: 'detection_timestamp_utc', 'transmitter_codespace', 'transmitter_id' and 'receiver_sn', as well as 'passed_filter' (see \code{\link[glatos]{false_detections}}).
+#' @param tf A number that defines the time threshold (s) used to flag false detections (see \code{\link[glatos]{false_detections}}).
+#' @param sf A number that defines the threshold Euclidean distance between receivers beyond which, even if a false detection is accompanied by detections at other receivers, it is likely to be a true false detection, because the individual could not have moved between receivers separated by more than this threshold over the specified time interval. \code{sf} should be defined in the same units as the distances provided in \code{dist_btw_receivers} (see below).
+#' @param dist_btw_receivers A dataframe that defines the distances between receiver pairs. This should contain the columns: 'r1', 'r2' and 'dist', whereby 'r1' and 'r2' contain the unique receiver serial number for all combinations of receivers and 'dist' contains the distance between them. This dataframe should include duplicate combinations (e.g., both r1 = 1 and r2 = 2 and r1 = 2 and r2 = 1). This can be created with \code{\link[flapper]{dist_btw_receivers}}.
 #'
 #' @details There are limitations with the application of this spatial filter to false detections. First, the spatial threshold beyond which false detections are likely to be false is based on Euclidean distances at present. These may be problematic (e.g. when receivers hug complex coastlines). Second, for small arrays, fast-swimming organisms and/or a large nominal transmission delay (i.e., time threshold), the spatial filter is a poor filter because individuals can access the whole area over the whole time interval.
 #'
@@ -338,10 +340,21 @@ process_false_detections_sf <-
 
 #' @title Basic quality checks of passive acoustic telemetry datasets
 #' @description This function passes through passive acoustic telemetry datasets through some basic quality checks (see Details). Following data processing, these provide a useful 'final check' prior to analysis.
+#'
 #' @param acoustics A dataframe which comprises passive acoustic telemetry detection time series. This must contain the following named columns: 'timestamp', a POSIXct vector which defines the time of each detection; 'receiver_id', a unique identifier of each receiver; and 'individual_id', a unique identifier of each individual (see \code{\link[flapper]{dat_acoustics}} for an example).
-#' @param moorings A dataframe which contains passive acoustic telemetry receiver metadata. This must contain the following named columns: '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 (see \code{\link[flapper]{dat_moorings}} for an example). If objects of class Date are provided for 'receiver_start_date' and 'receiver_end_date', these are coerced to POSIXct objects with a warning.
-#' @param ids A dataframe which contains the passive acoustic telemetry individual metadata. This must contain the following named columns: 'individual_id', a unique identifier for each individual; 'tag_start_date', a POSIXct vector which defines the time of each tag deployment; and 'tag_end_date', a POSIXct vector which defines the end of each tag deployment (see \code{\link[flapper]{dat_ids}} for an example). If objects of class Date are provided for 'tag_start_date' and 'tag_end_date', these are coerced to POSIXct objects with a warning.
-#' @details The function implements the following checks. (1) \code{acoustics} should only contain receivers recorded in \code{moorings}; other receivers may be included in centralised databases (e.g., from other projects) and often need to be removed. (2) Observations at receivers should occur during their deployment windows; other observations may be included in centralised databases due to receiver checks, range testing or re-deployment elsewhere. (3) \code{acoustics} is checked for any unknown tag IDs. These may be due unrecorded use of tags for receiver checking or range testing, other tagging programmes or type A false detections. (4) As for detections at receivers, all detections of tags should occur during their deployment windows. (5) False detections should be flagged. Other important checks - such as checking for receivers which were lost and later recovered, excluding observations during receiver servicing dates, excluding observations during tag recapture events and further investigation of false detections - may be required. \code{\link[flapper]{process_quality_check}} is mainly designed to be implemented after data-processing has already taken place as a basic 'final check' for common issues in passive acoustic telemetry datasets. For each check, the function returns a message or warning depending on the outcome; subsequently, the most appropriate course of action (e.g., retention versus removal of flagged observations in \code{acoustics} will depend on the context).
+#' @param moorings A dataframe which contains passive acoustic telemetry receiver metadata. This must contain the following named columns: 'receiver_id', a unique identifier for each receiver deployment; 'receiver_start_date', a POSIXct vector which defines the time of each receiver's deployment; and 'receiver_end_date', a POSIXct vector which defines the end of each receiver's deployment (see \code{\link[flapper]{dat_moorings}} for an example). If objects of class Date are provided for 'receiver_start_date' and 'receiver_end_date', these are coerced to POSIXct objects with a warning.
+#' @param ids A dataframe which contains the passive acoustic telemetry individual metadata. This must contain the following named columns: 'individual_id', a unique identifier for each individual; 'tag_start_date', a POSIXct vector which defines the time of each tag's deployment; and 'tag_end_date', a POSIXct vector which defines the end of each tag's deployment (see \code{\link[flapper]{dat_ids}} for an example). If objects of class Date are provided for 'tag_start_date' and 'tag_end_date', these are coerced to POSIXct objects with a warning.
+#'
+#' @details The function implements the following checks:
+#' \enumerate{
+#' \item Valid receivers. \code{acoustics} should only contain receivers recorded in \code{moorings}; other receivers may be included in centralised databases (e.g., from other projects) and often need to be removed.
+#' \item Valid detections (at receivers). Observations at receivers should occur during their deployment windows; other observations may be included in centralised databases due to receiver checks, range testing or re-deployment elsewhere.
+#' \item Valid tags. \code{acoustics} is checked for any unknown tag IDs. These may be due unrecorded use of tags for receiver checking or range testing, other tagging programmes or type A false detections.
+#' \item Valid detections (of tags). As for detections at receivers, all detections of tags should occur during their deployment windows.
+#' \item False detections. False detections should be flagged.
+#' }
+#'
+#' \code{\link[flapper]{process_quality_check}} is mainly designed to be implemented after data-processing has already taken place as a basic 'final check' for common issues in passive acoustic telemetry datasets. For each check, the function returns a message or warning depending on the outcome; subsequently, the most appropriate course of action (e.g., retention versus removal of flagged observations in \code{acoustics} will depend on the context). Other important checks -- such as checking for receivers which were lost and later recovered, excluding observations during receiver servicing dates, excluding observations during tag capture events and further investigation of false detections -- may be required.
 #'
 #' @return For each check, the function returns a message or a warning with relevant details.
 #'