feat: add new method backendRequiredSpectraVariables

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Spectra
 Title: Spectra Infrastructure for Mass Spectrometry Data
-Version: 1.15.11
+Version: 1.15.12
 Description: The Spectra package defines an efficient infrastructure
    for storing and handling mass spectrometry spectra and functionality to
    subset, process, visualize and compare spectra data. It provides different

NAMESPACE

@@ -71,6 +71,7 @@ exportMethods(backendBpparam)
 exportMethods(backendInitialize)
 exportMethods(backendMerge)
 exportMethods(backendParallelFactor)
+exportMethods(backendRequiredSpectraVariables)
 exportMethods(bin)
 exportMethods(c)
 exportMethods(centroided)
@@ -207,6 +208,7 @@ importFrom(methods,.hasSlot)
 importFrom(methods,.valueClassTest)
 importFrom(methods,as)
 importFrom(methods,callNextMethod)
+importFrom(methods,existsMethod)
 importFrom(methods,is)
 importFrom(methods,new)
 importFrom(methods,setAs)

NEWS.md

@@ -1,5 +1,10 @@
 # Spectra 1.15
 
+## Changes in 1.15.12
+
+- Add generic `backendRequiredSpectraVariables()` to allow definition of
+  mandatory spectra variables for a backend.
+
 ## Changes in 1.15.11
 
 - Add reference to `MsBackendMetaboLights`.

R/AllGenerics.R

@@ -1,6 +1,8 @@
 #' @include hidden_aliases.R
 NULL
 
+setGeneric("backendRequiredSpectraVariables", function(object, ...)
+          standardGeneric("backendRequiredSpectraVariables"))
 #' @rdname hidden_aliases
 setMethod("bin", "numeric", MsCoreUtils::bin)
 setGeneric("combinePeaks", function(object, ...)

R/MsBackend.R

@@ -17,6 +17,8 @@
 #' @aliases dataStorageBasePath<-,MsBackendMzR-method
 #' @aliases extractByIndex
 #' @aliases msLeveL<-,MsBackend-method
+#' @aliases backendRequiredSpectraVariables
+#' @aliases backendRequiredSpectraVariables,MsBackend-method
 #'
 #' @description
 #'
@@ -280,6 +282,13 @@
 #'   `MsBackendMzR` on the other hand returns `factor(dataStorage(object))`
 #'   hence suggesting to split the object by data file.
 #'
+#' - `backendRequiredSpectraVariables()`: returns a `character` with spectra
+#'   variable names that are mandatory for a specific backend. The default
+#'   returns an empty `character()`. The implementation for `MsBackendMzR`
+#'   returns `c("dataStorage", "scanIndex")` as these two spectra variables
+#'   are required to load the MS data on-the-fly. This method needs only to
+#'   be implemented if a backend requires specific variables to be defined.
+#'
 #' - `dataOrigin()`: gets a `character` of length equal to the number of
 #'   spectra in `object` with the *data origin* of each spectrum. This could
 #'   e.g. be the mzML file from which the data was read.
@@ -965,6 +974,12 @@ setMethod("backendParallelFactor", "MsBackend", function(object, ...) {
     factor()
 })
 
+#' @export
+setMethod("backendRequiredSpectraVariables", "MsBackend",
+          function(object, ...) {
+              character()
+          })
+
 #' @rdname MsBackend
 #'
 #' @export
@@ -1104,19 +1119,22 @@ setReplaceMethod("dataStorage", "MsBackend", function(object, value) {
 #' @export
 setMethod("dropNaSpectraVariables", "MsBackend", function(object) {
     svs <- spectraVariables(object)
-    svs <- svs[!(svs %in% c("mz", "intensity"))]
+    req_cols <- c(backendRequiredSpectraVariables(object), c("mz", "intensity"))
+    svs <- svs[!(svs %in% req_cols)]
     spd <- spectraData(object, columns = svs)
     keep <- !vapply1l(spd, function(z) {
         allna <- all(is.na(z))
         if (length(allna) > 1)
             FALSE
         else allna
     })
-    selectSpectraVariables(object, c(svs[keep], "mz", "intensity"))
+    selectSpectraVariables(object, c(svs[keep], req_cols))
 })
 
 #' @rdname MsBackend
 #'
+#' @importFrom methods existsMethod
+#'
 #' @export
 setMethod("extractByIndex", c("MsBackend", "ANY"), function(object, i) {
     if (existsMethod("[", class(object)[1L]))

R/MsBackendDataFrame.R

@@ -22,7 +22,8 @@ setClass("MsBackendDataFrame",
                                version = "0.2"))
 
 setValidity("MsBackendDataFrame", function(object) {
-    msg <- .valid_spectra_data_required_columns(object@spectraData)
+    msg <- .valid_spectra_data_required_columns(
+        object@spectraData, backendRequiredSpectraVariables(object))
     if (length(msg))
         return(msg)
     msg <- c(
@@ -92,6 +93,12 @@ setMethod("backendMerge", "MsBackendDataFrame", function(object, ...) {
     res
 })
 
+#' @rdname hidden_aliases
+setMethod("backendRequiredSpectraVariables", "MsBackendDataFrame",
+          function(object, ...) {
+              "dataStorage"
+          })
+
 ## Data accessors
 
 #' @rdname hidden_aliases
@@ -413,14 +420,16 @@ setMethod("selectSpectraVariables", "MsBackendDataFrame",
                        paste(spectraVariables[!(spectraVariables %in%
                                                 spectraVariables(object))],
                              collapse = ", "), " not available")
+              bv <- backendRequiredSpectraVariables(object)
+              if (!all(bv %in% spectraVariables))
+                  stop("Spectra variables ",
+                       paste(bv[!bv %in% spectraVariables], collapse = ","),
+                       " are required by the backend")
               keep <- spectraVariables[spectraVariables %in%
                                        colnames(object@spectraData)]
               if (length(keep))
                   object@spectraData <- object@spectraData[, keep,
                                                            drop = FALSE]
-              msg <- .valid_spectra_data_required_columns(object@spectraData)
-              if (length(msg))
-                  stop(msg)
               object@peaksVariables <- intersect(object@peaksVariables,
                                                  spectraVariables)
               validObject(object)

R/MsBackendHdf5Peaks.R

@@ -26,8 +26,8 @@ setClass("MsBackendHdf5Peaks",
          prototype = prototype(version = "0.1", readonly = FALSE))
 
 setValidity("MsBackendHdf5Peaks", function(object) {
-    msg <- .valid_spectra_data_required_columns(object@spectraData,
-                                                c("dataStorage", "scanIndex"))
+    msg <- .valid_spectra_data_required_columns(
+        object@spectraData, backendRequiredSpectraVariables(object))
     fls <- unique(object@spectraData$dataStorage)
     msg <- c(msg, .valid_ms_backend_mod_count(object@modCount, fls))
     msg <- c(msg, .valid_ms_backend_files_exist(fls))
@@ -36,6 +36,12 @@ setValidity("MsBackendHdf5Peaks", function(object) {
     else msg
 })
 
+#' @rdname hidden_aliases
+setMethod("backendRequiredSpectraVariables", "MsBackendHdf5Peaks",
+          function(object, ...) {
+              c("dataStorage", "scanIndex")
+          })
+
 #' @rdname hidden_aliases
 #'
 #' @importFrom fs path_sanitize

R/MsBackendMemory.R

@@ -122,6 +122,12 @@ setMethod("backendMerge", "MsBackendMemory", function(object, ...) {
     res
 })
 
+#' @rdname hidden_aliases
+setMethod("backendRequiredSpectraVariables", "MsBackendMemory",
+          function(object, ...) {
+              "dataStorage"
+          })
+
 ## Data accessors
 
 #' @rdname hidden_aliases
@@ -514,7 +520,8 @@ setMethod("selectSpectraVariables", "MsBackendMemory",
                                   z[, keep, drop = FALSE])
                   }
               }
-              msg <- .valid_spectra_data_required_columns(object@spectraData)
+              msg <- .valid_spectra_data_required_columns(
+                  object@spectraData, backendRequiredSpectraVariables(object))
               if (length(msg))
                   stop(msg)
               validObject(object)

R/MsBackendMzR.R

@@ -24,14 +24,20 @@ setClass("MsBackendMzR",
          prototype = prototype(version = "0.1", readonly = TRUE))
 
 setValidity("MsBackendMzR", function(object) {
-    msg <- .valid_spectra_data_required_columns(object@spectraData,
-                                                c("dataStorage", "scanIndex"))
+    msg <- .valid_spectra_data_required_columns(
+        object@spectraData, backendRequiredSpectraVariables(object))
     msg <- c(msg, .valid_ms_backend_files_exist(
                       unique(object@spectraData$dataStorage)))
     if (length(msg)) msg
     else TRUE
 })
 
+#' @rdname hidden_aliases
+setMethod("backendRequiredSpectraVariables", "MsBackendMzR",
+          function(object, ...) {
+              c("dataStorage", "scanIndex")
+          })
+
 #' @rdname hidden_aliases
 #'
 #' @importFrom methods callNextMethod

inst/test_backends/test_MsBackend/test_spectra_subsetting.R

@@ -92,8 +92,9 @@ test_that("selectSpectraVariables", {
     if (!isReadOnly(be) || inherits(be, "MsBackendCached") ||
         inherits(be, "MsBackendDataFrame")) {
         tmp <- be
-        res <- selectSpectraVariables(tmp, c("mz", "intensity",
-                                             "dataStorage", "scanIndex"))
+        res <- selectSpectraVariables(
+            tmp, union(c("mz", "intensity", "dataStorage", "scanIndex"),
+                       backendRequiredSpectraVariables(be)))
         expect_true(all(names(coreSpectraVariables()) %in%
                         spectraVariables(res)))
         expect_true(all(is.na(res$msLevel)))

tests/testthat/test_MsBackend.R

@@ -57,6 +57,7 @@ test_that("MsBackend methods throw errors", {
     expect_error(dm$a, "implemented for")
     expect_error(dm$a <- "a", "implemented for")
     expect_error(extractByIndex(dm, 1), "implemented for")
+    expect_equal(backendRequiredSpectraVariables(dm), character())
 })
 
 test_that("extractByIndex not implemented fallback", {

tests/testthat/test_MsBackendDataFrame.R

@@ -653,7 +653,7 @@ test_that("selectSpectraVariables,MsBackendDataFrame works", {
     expect_equal(colnames(res@spectraData), c("dataStorage", "rtime"))
     expect_equal(res@peaksVariables, be@peaksVariables)
 
-    expect_error(selectSpectraVariables(be, "rtime"), "dataStorage is/are missing")
+    expect_error(selectSpectraVariables(be, "rtime"), "are required")
     expect_error(selectSpectraVariables(be, "something"),
                  "something not available")
 
@@ -1024,3 +1024,8 @@ test_that("[[,[[<-,MsBackendDataFrame works", {
 test_that("supportsSetBackend,MsBackendDataFrame", {
     expect_true(supportsSetBackend(MsBackendDataFrame()))
 })
+
+test_that("backendRequiredSpectraVariables,MsBackendDataFrame works", {
+    expect_equal(backendRequiredSpectraVariables(MsBackendDataFrame()),
+                 "dataStorage")
+})

tests/testthat/test_MsBackendHdf5Peaks.R

@@ -413,3 +413,8 @@ test_that("backendParallelFactor,MsBackendHdf5Peaks", {
                  factor(dataStorage(sciex_hd5),
                         levels = unique(dataStorage(sciex_hd5))))
 })
+
+test_that("backendRequiredSpectraVariables,MsBackendHdf5Peaks works", {
+    expect_equal(backendRequiredSpectraVariables(MsBackendHdf5Peaks()),
+                 c("dataStorage", "scanIndex"))
+})

tests/testthat/test_MsBackendMemory.R

@@ -944,3 +944,8 @@ test_that("tic,MsBackendMemory works", {
 test_that("supportsSetBackend,MsBackendMemory", {
     expect_true(supportsSetBackend(MsBackendMemory()))
 })
+
+test_that("backendRequiredSpectraVariables,MsBackendMemory works", {
+    expect_equal(backendRequiredSpectraVariables(MsBackendMemory()),
+                 "dataStorage")
+})

tests/testthat/test_MsBackendMzR.R

@@ -504,7 +504,7 @@ test_that("selectSpectraVariables,MsBackendMzR works", {
     expect_equal(res@peaksVariables, c("mz", "intensity"))
 
     expect_error(selectSpectraVariables(be, c("dataStorage", "msLevel")),
-                 "scanIndex is/are missing")
+                 "required")
 })
 
 test_that("$,$<-,MsBackendMzR works", {
@@ -597,3 +597,9 @@ test_that("dataStorageBasePath,dataStorageBasePath<-,MsBackendMzR works", {
     #' errors
     expect_error(dataStorageBasePath(tmp) <- "some path", "Provided path")
 })
+
+test_that("backendRequiredSpectraVariables,MsBackendMzR works", {
+    tmp <- MsBackendMzR()
+    expect_equal(backendRequiredSpectraVariables(tmp),
+                 c("dataStorage", "scanIndex"))
+})