R/read_pp_swift.R

In adamdsmith/pinpoint: Scheduling fixes and reading and plotting data from Lotek PinPoint tags

#' Read processed Swift fixes from PinPoint Host software output
#'
#' This function reads the text file generated by the PinPoint Host software and
#'  generates a tidy data frame for further analysis.  The user can optionally
#'  remove unsuccessful fixes.
#'
#' @param swift_txt character scalar or vector containing path(s) to the *.txt file created
#'  by the PinPoint Host software when processing Swift fixes.  Default (`NULL`) prompts the
#'  user to select one or more files.
#' @param out_tz character string indicating the desired output \code{\link[base]{timezone}}
#'  of the GPS fixes.  Datetimes will be converted from the standard GMT time zone of
#'  PinPoint fixes. Default is America/New_York.
#' @param valid_only logical indicating whether unsuccessful GPS fix attempts should be
#'  removed from the output data frame.  The default (FALSE) retains the scheduled fixes
#'  that were unsuccessful.
#' @param deploy_df `data.frame`, `tibble` or `tbl_df` containing deployment and recovery
#'  information for PinPoint tags that will be used to filter tag data.  This object must
#'  contain at least the following three variables: `tag_id` - integer or numeric PinPoint
#'  tag identification number, `deploy_date` - `POSIXct` date of tag deployment, and
#'  `recov_date` - `POSIXct` date of tag recovery.  Currently, data on the day of deployment
#'  and recovery are ignored.
#' @importFrom lubridate ymd_hms ymd_hm
#' @export
#' @examples
#' \dontrun{
#' # Select apprpriate text files from file selection window that opens
#' pp_tests <- list.files(path = system.file("extdata", package = "pinpoint"), full.names = TRUE)
#' dat <- read_pp_swift(pp_tests)
#' }

read_pp_swift <- function(swift_txt = NULL, out_tz = "America/New_York", valid_only = FALSE,
                          deploy_df = NULL)
{

  if (is.null(swift_txt)) {
    txt_filt <- matrix(c("Text files (*.txt)", "*.txt"), nrow = 1)
    swift_txt <- utils::choose.files(default = "PinPoint", filters = txt_filt,
                           caption = "Select .txt files containing processed PinPoint Swift fixes.")
    if (length(swift_txt) == 0) stop("Function cancelled.  No PinPoint output files selected.")
  }
  if (length(swift_txt) == 1) {
    out <- read_tidy_pp(swift_txt, out_tz, valid_only)
  } else {
    out <- lapply(swift_txt, read_tidy_pp, out_tz = out_tz, valid_only = valid_only)
    out <- bind_rows(out)
  }

  if (!is.null(deploy_df)) {
    stopifnot(all(c("tag_id", "deploy_date", "recov_date") %in% names(deploy_df)))
    stopifnot(any(is.numeric(deploy_df$tag_id), is.integer(deploy_df$tag_id)))
    stopifnot(all(inherits(deploy_df$deploy_date, "POSIXct"),
                  inherits(deploy_df$recov_date, "POSIXct")))
    out <- out %>%
      left_join(deploy_df[c("tag_id", "deploy_date", "recov_date")], by = "tag_id") %>%
      group_by(.data$tag_id, .data$deploy_date) %>%
      filter(.data$date > .data$deploy_date, .data$date < .data$recov_date) %>% ungroup() %>%
      select(-.data$deploy_date, -.data$recov_date)
  }
  class(out) <- c("pp_df", "data.frame")
  out
}