R/writeQC.R

In IMOS-AnimalTracking/remora: Rapid Extraction of Marine Observations for Roving Animals

##' @title write a QCsummary.csv file and/or QC processed \code{.csv} files for each tag deployment
##'
##' @description writes a single QCsummary.csv file and/or tag-deployment-specific \code{temporal_outcome}'s 
##' of quality-controlled detections to \code{.csv} files
##'
##' @param x a nested tibble with class `remora_QC` generated by \code{runQC}
##' @param path path to write QC'd files to. If NULL the files are written to
##' the working directory
##' @param summary whether to generate a summary \code{.csv} file. If TRUE then
##' `QCsummary.csv` is written to the specified \code{path}
##' @param csv whether to generate the individual \code{.csv} files. If TRUE (default) then
##' each file is written to the specified \code{path}
##'
##' @details takes a `remora_QC` nested tibble and writes .csv files
##' corresponding to each row of the nested tibble. A summary of the QC process
##' is written to `QCsummary.csv`. The summary contains the following information for each QC'd tag 
##' (see references for more details):
##' * total detections - the number of raw detections
##' * detections_before_deployment - the number of detections recorded prior to deployment date in metadata
##' * invalid_deployment_location - logical indicating whether deployment longitude,latitude is valid
##' * detections_outside_species_range - the number of detections that occurred outside the species expert distribution
##' * valid_detections - the number of detections that passed the QC process (QC flags 1 and 2)
##' * tracking_duration_days - the number of days between deployment and the last valid detection
##' * invalid_velocity - the number of detections associated with implausible travel speeds
##'
##' @return .csv files and/or a QCsummary.csv file are written to the specified \code{path}
##'
##' @md
##' 
##' @examples
##' \dontrun{
##' ## example QC'd data
##' data(TownsvilleReefQC)
##' ## write QC output
##' writeQC(TownsvilleReefQC, summary = TRUE)
##' }
##' 
##' @references Hoenner X et al. (2018) Australia’s continental-scale acoustic tracking database and its automated quality control process. Sci Data 5, 170206 https://doi.org/10.1038/sdata.2017.206
##' 
##' @importFrom readr write_delim
##' 
##' @export

writeQC <- function(x, path = NULL, summary = TRUE, csv = TRUE) {

  if(is.null(path)) {
    path <- getwd()
  }

  if(!inherits(x, "remora_QC")) stop("x must be a nested tibble with class `remora_QC`")
  
  files <- x$filename

  if (csv) {
    message("Writing all QC output files...\n")
    lapply(1:length(files), function(i) {
      ## check whether shortest_dist.R produced a correct result,
      ##   if so then write the temporal_outcome file
      if (is.data.frame(x[i, ])) {
        write_delim(
          x$QC[[i]],
          file = paste0(file.path(path, files[i]), ".csv"),
          delim = ";",
          col_names = TRUE,
          quote_escape = FALSE
        )
      }
    })
  }

  if (summary) {
    message("Writing `QCsummary.csv` file...\n")
    write_summary(x, path = path)
  }
  
  if (!csv & !summary) stop("No output files specified, nothing to do...\n")
}