diff --git a/DESCRIPTION b/DESCRIPTION index 1fad99af..8247f945 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,8 +2,8 @@ Package: glatos Type: Package Title: A package for the Great Lakes Acoustic Telemetry Observation System Description: Functions useful to members of the Great Lakes Acoustic Telemetry Observation System https://glatos.glos.us; many more broadly relevant to simulating, processing, analysing, and visualizing acoustic telemetry data. -Version: 0.8.0.9000 -Date: 2024-01-04 +Version: 0.8.0.9001 +Date: 2024-01-13 Depends: R (>= 3.5.0) Imports: av, diff --git a/NEWS.md b/NEWS.md index 1300a864..5393bdbd 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,6 +4,10 @@ ### Bug fixes +- Omit data.table from class of object returned by `read_glatos_detections()` + and `read_glatos_receivers()`. + - fixes [issue #200](https://github.com/ocean-tracking-network/glatos/issues/200) + - Fix typo in Description to Suggest 'gifski' (not 'gifsky'). - fixes [issue #185](https://github.com/ocean-tracking-network/glatos/issues/185) diff --git a/R/load-read_glatos_detections.r b/R/load-read_glatos_detections.r index 7ca5151e..3ec9fbcb 100644 --- a/R/load-read_glatos_detections.r +++ b/R/load-read_glatos_detections.r @@ -1,135 +1,137 @@ -#' @title Read data from a GLATOS detection file -#' -#' @description Read data from a standard GLATOS detection (csv) file and return -#' a data.frame of class `glatos_detections`. -#' -#' @param det_file A character string with path and name of detection file in -#' standard GLATOS format (*.csv). If only file name is given, then the file -#' must be located in the working directory. File must be a standard GLATOS -#' file (e.g., *xxxxx_detectionsWithLocs_yyyymmdd_hhmmss.csv*) submitted via -#' GLATOSWeb Data Portal . -#' -#' @param version An optional character string with the glatos file version -#' number. If NULL (default value) then version will be determined by -#' evaluating file structure. The only allowed values currently are `NULL`, -#' `"1.3"`, and `"1.4"`. Any other values will trigger an error. Users should -#' never need to set this argument (`NULL` should work). -#' -#' @details Data are loaded using [fread][data.table::fread] and timestamps are -#' coerced to POSIXct using [fastPOSIXct][fasttime::fastPOSIXct]. All times must -#' be in UTC timezone per GLATOS standard. -#' -#' @details Column `animal_id` is considered a required column by many other -#' functions in this package, so it will be created if any records are `NULL`. -#' When created, it will be constructed from `transmitter_codespace` and -#' `transmitter_id`, separated by '-'. -#' -#' @return A data.frame of class `glatos_detections`. -#' -#' @author C. Holbrook \email{cholbrook@@usgs.gov} -#' -#' @examples -#' # get path to example detection file -#' det_file <- system.file("extdata", "walleye_detections.csv", -#' package = "glatos" -#' ) -#' -#' # note that code above is needed to find the example file -#' # for real glatos data, use something like below -#' # det_file <- "c:/path_to_file/HECWL_detectionsWithLocs_20150321_132242.csv" -#' -#' det <- read_glatos_detections(det_file) -#' -#' @importFrom lubridate parse_date_time -#' -#' @export -read_glatos_detections <- function(det_file, version = NULL) { - # Read detection file------------------------------------------------------- - - # see version-specific file specifications - # internal data object; i.e., in R/sysdata.r - - - # Identify detection file version - id_det_version <- function(det_file) { - det_col_names <- names(data.table::fread(det_file, nrows = 0)) - if (all(glatos:::glatos_detection_schema$v1.4$name %in% det_col_names)) { - return("1.4") - } else if (all(glatos:::glatos_detection_schema$v1.3$name %in% det_col_names)) { - return("1.3") - } else { - stop("Detection file version could not be identified.") - } - } - - if (is.null(version)) { - version <- id_det_version(det_file) - } else if (!(paste0("v", version) %in% - names(glatos:::glatos_detection_schema))) { - stop(paste0("Detection file version ", version, " is not supported.")) - } - - #-Detections v1.3 or v1.4----------------------------------------------------- - if (version %in% c("1.3", "1.4")) { - vversion <- paste0("v", version) - - col_classes <- glatos:::glatos_detection_schema[[vversion]]$type - timestamp_cols <- which(col_classes == "POSIXct") - date_cols <- which(col_classes == "Date") - col_classes[c(timestamp_cols, date_cols)] <- "character" - - # read data - dtc <- data.table::fread(det_file, - sep = ",", colClasses = col_classes, - na.strings = c("", "NA") - ) - - # coerce timestamps to POSIXct; note that with fastPOSIXct raw - # timestamp must be in UTC; and tz argument sets the tzone attr only - options(lubridate.fasttime = TRUE) - for (j in timestamp_cols) { - data.table::set(dtc, - j = glatos:::glatos_detection_schema[[vversion]]$name[j], - value = lubridate::parse_date_time( - dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]], - orders = "ymd HMS", - tz = "UTC" - ) - ) - } - # coerce dates to date - for (j in date_cols) { - data.table::set(dtc, - j = glatos:::glatos_detection_schema[[vversion]]$name[j], - value = ifelse(dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]] == "", - NA, - dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]] - ) - ) - data.table::set(dtc, - j = glatos:::glatos_detection_schema[[vversion]]$name[j], - value = as.Date(dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]]) - ) - } - } - #-end v1.3 or v1.4------------------------------------------------------------ - - # create animal_id if missing - anid_na <- is.na(dtc$animal_id) - if (any(anid_na)) { - dtc$animal_id[anid_na] <- with( - dtc, - paste0(transmitter_codespace[anid_na], "-", transmitter_id[anid_na]) - ) - warning(paste0( - "Some or all values of required column 'animal_id' were ", - "missing so they were created from 'transmitter_codespace' and ", - "'transmitter_id'.)" - )) - } - - # assign class - dtc <- as_glatos_detections(dtc) - - return(dtc) -} +#' @title Read data from a GLATOS detection file +#' +#' @description Read data from a standard GLATOS detection (csv) file and return +#' a data.frame of class `glatos_detections`. +#' +#' @param det_file A character string with path and name of detection file in +#' standard GLATOS format (*.csv). If only file name is given, then the file +#' must be located in the working directory. File must be a standard GLATOS +#' file (e.g., *xxxxx_detectionsWithLocs_yyyymmdd_hhmmss.csv*) submitted via +#' GLATOSWeb Data Portal . +#' +#' @param version An optional character string with the glatos file version +#' number. If NULL (default value) then version will be determined by +#' evaluating file structure. The only allowed values currently are `NULL`, +#' `"1.3"`, and `"1.4"`. Any other values will trigger an error. Users should +#' never need to set this argument (`NULL` should work). +#' +#' @details Data are loaded using [fread][data.table::fread] and timestamps are +#' coerced to POSIXct using [fastPOSIXct][fasttime::fastPOSIXct]. All times must +#' be in UTC timezone per GLATOS standard. +#' +#' @details Column `animal_id` is considered a required column by many other +#' functions in this package, so it will be created if any records are `NULL`. +#' When created, it will be constructed from `transmitter_codespace` and +#' `transmitter_id`, separated by '-'. +#' +#' @return A data.frame of class `glatos_detections`. +#' +#' @author C. Holbrook \email{cholbrook@@usgs.gov} +#' +#' @examples +#' # get path to example detection file +#' det_file <- system.file("extdata", "walleye_detections.csv", +#' package = "glatos" +#' ) +#' +#' # note that code above is needed to find the example file +#' # for real glatos data, use something like below +#' # det_file <- "c:/path_to_file/HECWL_detectionsWithLocs_20150321_132242.csv" +#' +#' det <- read_glatos_detections(det_file) +#' +#' @importFrom lubridate parse_date_time +#' +#' @export +read_glatos_detections <- function(det_file, version = NULL) { + # Read detection file------------------------------------------------------- + + # see version-specific file specifications + # internal data object; i.e., in R/sysdata.r + + + # Identify detection file version + id_det_version <- function(det_file) { + det_col_names <- names(data.table::fread(det_file, nrows = 0)) + if (all(glatos:::glatos_detection_schema$v1.4$name %in% det_col_names)) { + return("1.4") + } else if (all(glatos:::glatos_detection_schema$v1.3$name %in% det_col_names)) { + return("1.3") + } else { + stop("Detection file version could not be identified.") + } + } + + if (is.null(version)) { + version <- id_det_version(det_file) + } else if (!(paste0("v", version) %in% + names(glatos:::glatos_detection_schema))) { + stop(paste0("Detection file version ", version, " is not supported.")) + } + + #-Detections v1.3 or v1.4----------------------------------------------------- + if (version %in% c("1.3", "1.4")) { + vversion <- paste0("v", version) + + col_classes <- glatos:::glatos_detection_schema[[vversion]]$type + timestamp_cols <- which(col_classes == "POSIXct") + date_cols <- which(col_classes == "Date") + col_classes[c(timestamp_cols, date_cols)] <- "character" + + # read data + dtc <- data.table::fread(det_file, + sep = ",", colClasses = col_classes, + na.strings = c("", "NA") + ) + + # coerce timestamps to POSIXct; note that with fastPOSIXct raw + # timestamp must be in UTC; and tz argument sets the tzone attr only + options(lubridate.fasttime = TRUE) + for (j in timestamp_cols) { + data.table::set(dtc, + j = glatos:::glatos_detection_schema[[vversion]]$name[j], + value = lubridate::parse_date_time( + dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]], + orders = "ymd HMS", + tz = "UTC" + ) + ) + } + # coerce dates to date + for (j in date_cols) { + data.table::set(dtc, + j = glatos:::glatos_detection_schema[[vversion]]$name[j], + value = ifelse(dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]] == "", + NA, + dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]] + ) + ) + data.table::set(dtc, + j = glatos:::glatos_detection_schema[[vversion]]$name[j], + value = as.Date(dtc[[glatos:::glatos_detection_schema[[vversion]]$name[j]]]) + ) + } + } + #-end v1.3 or v1.4------------------------------------------------------------ + + # create animal_id if missing + anid_na <- is.na(dtc$animal_id) + if (any(anid_na)) { + dtc$animal_id[anid_na] <- with( + dtc, + paste0(transmitter_codespace[anid_na], "-", transmitter_id[anid_na]) + ) + warning(paste0( + "Some or all values of required column 'animal_id' were ", + "missing so they were created from 'transmitter_codespace' and ", + "'transmitter_id'.)" + )) + } + + # strip data.table and assign glatos_detections class + data.table::setDF(dtc) + + dtc <- as_glatos_detections(dtc) + + return(dtc) +} diff --git a/R/load-read_glatos_receivers.r b/R/load-read_glatos_receivers.r index 1a184aaa..c373c3a4 100644 --- a/R/load-read_glatos_receivers.r +++ b/R/load-read_glatos_receivers.r @@ -1,116 +1,118 @@ -#' Read data from a GLATOS receiver location file -#' -#' Read data from a standard GLATOS receiver location (csv) file and return a -#' data.frame of class `glatos_receivers`. -#' -#' @param rec_file A character string with path and name of receiver location -#' file in standard GLATOS format (*.csv). If only file name is given, then -#' the file must be located in the working directory. File must be a standard -#' GLATOS file (e.g., *GLATOS_receiverLocations_yyyymmdd_xxxxxx.csv*) obtained -#' from GLATOSWeb Data Portal . -#' -#' @param version An optional character string with the GLATOS file version -#' number. If NULL (default value) then version will be determined by -#' evaluating file structure. The only allowed values currently are `NULL` and -#' `"1.0"`. Any other values will trigger an error. -#' -#' @details Data are loaded using [fread][data.table::fread] and timestamps are -#' coerced to POSIXct using [fastPOSIXct][fasttime::fastPOSIXct]. All -#' timestamps must be 'YYYY-MM-DD HH:MM' format and in UTC timezone per GLATOS -#' standard. -#' -#' @return A data.frame of class `glatos_receivers`. -#' -#' @author C. Holbrook (cholbrook@usgs.gov) -#' -#' @examples -#' # get path to example receiver_locations file -#' rec_file <- system.file("extdata", -#' "sample_receivers.csv", -#' package = "glatos" -#' ) -#' -#' # note that code above is needed to find the example file -#' # for real glatos data, use something like below -#' # rec_file <- "c:/path_to_file/GLATOS_receiverLocations_20150321_132242.csv" -#' -#' rcv <- read_glatos_receivers(rec_file) -#' -#' @importFrom lubridate parse_date_time -#' -#' @export -read_glatos_receivers <- function(rec_file, version = NULL) { - # Read source file------------------------------------------------------- - - # see version-specific file specifications - # internal data object; i.e., in R/sysdata.r - - - # Identify file version - id_file_version <- function(rec_file) { - col_names <- names(data.table::fread(rec_file, nrows = 0)) - if (all(glatos:::glatos_receivers_schema$v1.1$name %in% col_names)) { - return("1.1") - } else if (all(glatos:::glatos_receivers_schema$v1.0$name %in% col_names)) { - return("1.0") - } else { - stop("Receiver location file version could not be identified.") - } - } - - if (is.null(version)) { - version <- id_file_version(rec_file) - } else if (!(paste0("v", version) %in% - names(glatos:::glatos_receivers_schema))) { - stop(paste0( - "Receiver locations file version ", version, - " is not supported." - )) - } - - #-v1.x---------------------------------------------------------------- - if (version %in% c("1.0", "1.1")) { - ver_txt <- paste0("v", version) - - col_classes <- glatos:::glatos_receivers_schema[[ver_txt]]$type - timestamp_cols <- which(col_classes == "POSIXct") - date_cols <- which(col_classes == "Date") - col_classes[c(timestamp_cols, date_cols)] <- "character" - - # read data - rec <- data.table::fread(rec_file, sep = ",", colClasses = col_classes) - - # coerce timestamps to POSIXct; note that with fastPOSIXct raw - # timestamp must be in UTC; and tz argument sets the tzone attr only - options(lubridate.fasttime = TRUE) - for (j in timestamp_cols) { - data.table::set(rec, - j = glatos_receivers_schema[[ver_txt]]$name[j], - value = lubridate::parse_date_time( - rec[[glatos_receivers_schema[[ver_txt]]$name[j]]], - orders = "ymd HMS", - tz = "UTC" - ) - ) - } - # coerce dates to date - for (j in date_cols) { - data.table::set(rec, - j = glatos_receivers_schema[[ver_txt]]$name[j], - value = ifelse(rec[[glatos_receivers_schema[[ver_txt]]$name[j]]] == "", - NA, rec[[glatos_receivers_schema[[ver_txt]]$name[j]]] - ) - ) - data.table::set(rec, - j = glatos_receivers_schema[[ver_txt]]$name[j], - value = as.Date(rec[[glatos_receivers_schema[[ver_txt]]$name[j]]]) - ) - } - } - #-end v1.x---------------------------------------------------------------- - - # assign class - rec <- as_glatos_receivers(rec) - - return(rec) -} +#' Read data from a GLATOS receiver location file +#' +#' Read data from a standard GLATOS receiver location (csv) file and return a +#' data.frame of class `glatos_receivers`. +#' +#' @param rec_file A character string with path and name of receiver location +#' file in standard GLATOS format (*.csv). If only file name is given, then +#' the file must be located in the working directory. File must be a standard +#' GLATOS file (e.g., *GLATOS_receiverLocations_yyyymmdd_xxxxxx.csv*) obtained +#' from GLATOSWeb Data Portal . +#' +#' @param version An optional character string with the GLATOS file version +#' number. If NULL (default value) then version will be determined by +#' evaluating file structure. The only allowed values currently are `NULL` and +#' `"1.0"`. Any other values will trigger an error. +#' +#' @details Data are loaded using [fread][data.table::fread] and timestamps are +#' coerced to POSIXct using [fastPOSIXct][fasttime::fastPOSIXct]. All +#' timestamps must be 'YYYY-MM-DD HH:MM' format and in UTC timezone per GLATOS +#' standard. +#' +#' @return A data.frame of class `glatos_receivers`. +#' +#' @author C. Holbrook (cholbrook@usgs.gov) +#' +#' @examples +#' # get path to example receiver_locations file +#' rec_file <- system.file("extdata", +#' "sample_receivers.csv", +#' package = "glatos" +#' ) +#' +#' # note that code above is needed to find the example file +#' # for real glatos data, use something like below +#' # rec_file <- "c:/path_to_file/GLATOS_receiverLocations_20150321_132242.csv" +#' +#' rcv <- read_glatos_receivers(rec_file) +#' +#' @importFrom lubridate parse_date_time +#' +#' @export +read_glatos_receivers <- function(rec_file, version = NULL) { + # Read source file------------------------------------------------------- + + # see version-specific file specifications + # internal data object; i.e., in R/sysdata.r + + + # Identify file version + id_file_version <- function(rec_file) { + col_names <- names(data.table::fread(rec_file, nrows = 0)) + if (all(glatos:::glatos_receivers_schema$v1.1$name %in% col_names)) { + return("1.1") + } else if (all(glatos:::glatos_receivers_schema$v1.0$name %in% col_names)) { + return("1.0") + } else { + stop("Receiver location file version could not be identified.") + } + } + + if (is.null(version)) { + version <- id_file_version(rec_file) + } else if (!(paste0("v", version) %in% + names(glatos:::glatos_receivers_schema))) { + stop(paste0( + "Receiver locations file version ", version, + " is not supported." + )) + } + + #-v1.x---------------------------------------------------------------- + if (version %in% c("1.0", "1.1")) { + ver_txt <- paste0("v", version) + + col_classes <- glatos:::glatos_receivers_schema[[ver_txt]]$type + timestamp_cols <- which(col_classes == "POSIXct") + date_cols <- which(col_classes == "Date") + col_classes[c(timestamp_cols, date_cols)] <- "character" + + # read data + rec <- data.table::fread(rec_file, sep = ",", colClasses = col_classes) + + # coerce timestamps to POSIXct; note that with fastPOSIXct raw + # timestamp must be in UTC; and tz argument sets the tzone attr only + options(lubridate.fasttime = TRUE) + for (j in timestamp_cols) { + data.table::set(rec, + j = glatos_receivers_schema[[ver_txt]]$name[j], + value = lubridate::parse_date_time( + rec[[glatos_receivers_schema[[ver_txt]]$name[j]]], + orders = "ymd HMS", + tz = "UTC" + ) + ) + } + # coerce dates to date + for (j in date_cols) { + data.table::set(rec, + j = glatos_receivers_schema[[ver_txt]]$name[j], + value = ifelse(rec[[glatos_receivers_schema[[ver_txt]]$name[j]]] == "", + NA, rec[[glatos_receivers_schema[[ver_txt]]$name[j]]] + ) + ) + data.table::set(rec, + j = glatos_receivers_schema[[ver_txt]]$name[j], + value = as.Date(rec[[glatos_receivers_schema[[ver_txt]]$name[j]]]) + ) + } + } + #-end v1.x---------------------------------------------------------------- + + # strip data.table and assign glatos_receivers class + data.table::setDF(rec) + + rec <- as_glatos_receivers(rec) + + return(rec) +}