Additional ADAT "get" helpers

- new `getSomaScanVersion()` and `checkSomaScanVersion()` functions
- reorganized docs to merge with `getAdatVersion()`
- getAdatVersion()` now takes the full attributes
  as its input, rather than `x$Header.Meta`
- updated documentation
- fixes #83

NAMESPACE

@@ -65,6 +65,7 @@ export(anti_join)
 export(antilog)
 export(apt2seqid)
 export(arrange)
+export(checkSomaScanVersion)
 export(cleanNames)
 export(col2rn)
 export(collapseAdats)
@@ -80,6 +81,7 @@ export(getFeatures)
 export(getMeta)
 export(getSeqId)
 export(getSeqIdMatches)
+export(getSomaScanVersion)
 export(getSomamerData)
 export(getSomamers)
 export(getTargetNames)

R/adat-helpers.R

@@ -0,0 +1,101 @@
+#' Helpers to Extract Information from an ADAT
+#'
+#' [getAdatVersion()] determines the the ADAT version
+#'   number from a parsed ADAT header.\cr\cr
+#' [getSomaScanVersion()] determines the version of
+#'   SomaScan assay that a `soma_adat` object was run on.
+#'   These are elements of the `HEADER` attributes of the object.\cr\cr
+#' [checkSomaScanVersion()] determines if the version of
+#'   is a recognized version of SomaScan.\cr
+#' \cr
+#' Table of current SomaScan Assay versions:
+#' \tabular{lll}{
+#'   **Version**  \tab **Name** \tab **Size** \cr
+#'   `V4`         \tab 5k       \tab 5284     \cr
+#'   `v4.1`       \tab 7k       \tab 7596     \cr
+#'   `v5.0`       \tab 11k      \tab 11083    \cr
+#' }
+#'
+#' @name adat-helpers
+#' @param atts The *attributes* of a `soma_adat` object.
+#' @return Either a character string of length 1, or `NULL`.
+#'   \item{[getAdatVersion()]}{The key-value of the `Version` as a string.}
+#'   \item{[getSomaScanVersion()]}{The key-value of the `AssayVersion` as a string.}
+#'   \item{[checkSomaScanVersion()]}{Returns `NULL` (invisibly) if checks pass.}
+#' @author Stu Field
+#' @examples
+#' atts <- attributes(example_data)
+#' getAdatVersion(atts)
+#'
+#' atts$Header.Meta$HEADER$Version <- "1.0"
+#' getAdatVersion(atts)
+#' @export
+getAdatVersion <- function(atts) {
+
+  x <- atts$Header.Meta$HEADER
+  vidx <- grep("^Version$|^AdatVersion$", names(x))
+
+  if ( length(vidx) == 0L ) {
+    stop(
+      "Unable to identify ADAT Version from Header information. ",
+      "Please check 'Header.Meta'.", call. = FALSE
+    )
+  }
+
+  version <- as.character(x[[vidx]])
+
+  if ( length(version) > 1L ) {
+    warning(
+      "Version length > 1 ... there may be empty tabs in ",
+      "the header block above the data matrix.", call. = FALSE
+    )
+    version <- version[1L]
+  }
+
+  if ( identical(version, "1.01") ) {
+    stop(
+      "Invalid Version (", .value("1.01"), "). Please modify to `1.0.1`.",
+      call. = FALSE
+    )
+  }
+  version
+}
+
+
+.ss_ver_map <- c(v3 = "1129", v3.0 = "1129",
+                 v4 = "5k", v4.0 = "5k",
+                 v4.1 = "7k",
+                 v5  = "11k", v5.0 = "11k")
+
+
+#' Gets the SomaScan version
+#'
+#' @rdname adat-helpers
+#' @inheritParams is_intact_attr
+#' @examples
+#'
+#' ver <- getSomaScanVersion(example_data)
+#' ver
+#' @export
+getSomaScanVersion <- function(adat) {
+  as.character(attr(adat, "Header.Meta")$HEADER$AssayVersion)
+}
+
+
+#' Checks the SomaScan version
+#'
+#' @rdname adat-helpers
+#' @param ver `character(1)`. The SomaScan version as a string.
+#' @note The `"v"` is case insensitive.
+#' @examples
+#'
+#' is.null(checkSomaScanVersion(ver))
+#' @export
+checkSomaScanVersion <- function(ver) {
+  allowed <- c("v3.0", "v4", "v4.0", "v4.1", "v5", "v5.0")
+  if ( !tolower(ver) %in% allowed ) {
+    stop("Unsupported assay version: ", .value(ver),
+         ". Supported versions: ", .value(allowed), call. = FALSE)
+  }
+  invisible(NULL)
+}

R/parseHeader.R

@@ -131,7 +131,7 @@ parseHeader <- function(file) {
   }
 
   # TRUE if old adat version
-  ret$file_specs$old_adat <- getAdatVersion(ret$Header.Meta) < "1.0.0"
+  ret$file_specs$old_adat <- getAdatVersion(ret) < "1.0.0"
   ret
 }
 

R/s3-print-soma-adat.R

@@ -23,10 +23,12 @@ print.soma_adat <- function(x, show_header = FALSE, ...) {
   col_f       <- if ( attsTRUE ) cr_green else cr_red
   atts_symbol <- if ( attsTRUE ) symb_tick else symb_cross
   meta   <- getMeta(x)
+  ver    <- getSomaScanVersion(x)
   n_apts <- getAnalytes(x, n = TRUE)
   pad    <- strrep(" ", 5L)
-  dim_vars <- c("Attributes intact", "Rows", "Columns", "Clinical Data", "Features")
-  dim_vals <- c(col_f(atts_symbol), nrow(x), ncol(x), length(meta), n_apts)
+  dim_vars <- c("SomaScan version", "Attributes intact", "Rows",
+                "Columns", "Clinical Data", "Features")
+  dim_vals <- c(ver, col_f(atts_symbol), nrow(x), ncol(x), length(meta), n_apts)
   if ( inherits(x, "grouped_df") && !is.null(attr(x, "groups")) ) {
     dim_vars <- c(dim_vars, "Groups")
     group_data <- attr(x, "groups")

tests/testthat/test-getAdatVersion.R

@@ -1,21 +1,22 @@
 
+x <- list(Header.Meta = list(HEADER = list(Version = "1.2")))
+
 test_that("`getAdatVersion()` returns the ADAT version string", {
-  x <- list(HEADER = list(Version = "1.2"))
   expect_equal(getAdatVersion(x), "1.2")
-  x <- list(HEADER = list(Version = "2.5"))
+  x$Header.Meta$HEADER$Version <- "2.5"
   expect_equal(getAdatVersion(x), "2.5")
 })
 
 test_that("`getAdatVersion()` errors out if no `Version` in HEADER", {
-  x <- list(HEADER = list(Dummy = "Cox", Yellow = 3))
+  x$Header.Meta$HEADER <- list(Dummy = "Cox", Yellow = 3)
   expect_error(
     getAdatVersion(x),
     "Unable to identify ADAT Version from Header information."
   )
 })
 
 test_that("`getAdatVersion()` throws warning if tabs after key-value pair", {
-  x <- list(HEADER = list(Version = c("1.2", "\t")))
+  x$Header.Meta$HEADER$Version <- c("1.2", "\t")
   expect_warning(
     y <- getAdatVersion(x),
     paste("Version length > 1 ... there may be empty tabs",
@@ -25,7 +26,7 @@ test_that("`getAdatVersion()` throws warning if tabs after key-value pair", {
 })
 
 test_that("`getAdatVersion()` catches JAVA version number format", {
-  x <- list(HEADER = list(Version = "1.01"))
+  x$Header.Meta$HEADER$Version <- "1.01"
   expect_error(
     getAdatVersion(x),
     "Invalid Version ('1.01'). Please modify to `1.0.1`.",

tests/testthat/test-getSomaScanVersion.R

@@ -0,0 +1,14 @@
+
+test_that("`getSomaScanVersion()` returns the ADAT version string", {
+  expect_equal(getSomaScanVersion(example_data), "V4")
+})
+
+test_that("`checkSomaScanVersion()` returns the correct error mode", {
+  expect_null(checkSomaScanVersion("V4"))
+  expect_null(checkSomaScanVersion("v4"))
+  expect_null(checkSomaScanVersion("v4.1"))
+  expect_null(checkSomaScanVersion("v5.0"))
+  expect_null(checkSomaScanVersion("v5"))
+  expect_error(checkSomaScanVersion("V2"), "Unsupported")
+  expect_error(checkSomaScanVersion("foo"), "Unsupported")
+})