Addition of cbind2()

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Spectra
 Title: Spectra Infrastructure for Mass Spectrometry Data
-Version: 1.13.8
+Version: 1.15.0
 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
@@ -73,7 +73,7 @@ BugReports: https://github.com/RforMassSpectrometry/Spectra/issues
 URL: https://github.com/RforMassSpectrometry/Spectra
 biocViews: Infrastructure, Proteomics, MassSpectrometry, Metabolomics
 Encoding: UTF-8
-RoxygenNote: 7.3.1
+RoxygenNote: 7.3.2
 Roxygen: list(markdown=TRUE)
 Collate:
     'hidden_aliases.R'

NAMESPACE

@@ -70,6 +70,7 @@ exportMethods(backendMerge)
 exportMethods(backendParallelFactor)
 exportMethods(bin)
 exportMethods(c)
+exportMethods(cbind2)
 exportMethods(centroided)
 exportMethods(collisionEnergy)
 exportMethods(combinePeaks)
@@ -296,4 +297,5 @@ importMethodsFrom(S4Vectors,extractROWS)
 importMethodsFrom(S4Vectors,isEmpty)
 importMethodsFrom(S4Vectors,lapply)
 importMethodsFrom(S4Vectors,split)
+importMethodsFrom(methods,cbind2)
 importMethodsFrom(methods,show)

NEWS.md

@@ -1,4 +1,9 @@
-# Spectra 1.13
+# Spectra 1.15
+
+## Changes in 1.15.0
+
+- Add `cbind2()` method to easily add multiple `spectraVariables` to the
+  `spectraData`
 
 ## Changes in 1.13.8
 

R/MsBackend.R

@@ -178,6 +178,10 @@
 #'     values to filter the `object`. `values` needs to be of same length than
 #'     parameter `spectraVariables` and in the same order.
 #'
+#' @param y for `cbind2()`: A `data.frame` or `DataFrame` with the
+#'        spectra variables to be added to the backend. Need to be of the same
+#'        length as the number of spectra in the backend.
+#'
 #' @param x Object extending `MsBackend`.
 #'
 #' @param ... Additional arguments.
@@ -286,6 +290,11 @@
 #'   `dropNaSpectraVariables()` might still show columns containing `NA` values
 #'   for *core* spectra variables.
 #'
+#' - `cbind2()`: allows to appends multiple spectra variables to the backend at
+#'   once. It does so *blindly* and is therefore at the risk of the user. For a
+#'   more controlled way of adding spectra variables, the `joinSpectraData()`
+#'   should be used.
+#'
 #' - `centroided()`, `centroided<-`: gets or sets the centroiding
 #'   information of the spectra. `centroided()` returns a `logical`
 #'   vector of length equal to the number of spectra with `TRUE` if a
@@ -960,6 +969,26 @@ setMethod("peaksVariables", "MsBackend", function(object) {
     c("mz", "intensity")
 })
 
+
+setClassUnion("dataframeOrDataFrameOrmatrix", c("data.frame", "DataFrame", "matrix"))
+#' @exportMethod cbind2
+#'
+#' @importMethodsFrom methods cbind2
+#'
+#' @rdname MsBackend
+setMethod("cbind2", signature = c("MsBackend", "dataframeOrDataFrameOrmatrix"),
+          function(x, y = data.frame(), ...) {
+    if (is(y, "matrix"))
+        y <- as.data.frame(y)
+    if (nrow(y) != length(x))
+        stop("Length of 'y' does not match the number of spectra in 'x'")
+    for (i in colnames(y)) {
+        x[[i]] <- y[, i]
+    }
+    x
+})
+
+
 #' @exportMethod centroided
 #'
 #' @aliases centroided<-,MsBackend-method

R/MsBackendDataFrame.R

@@ -548,6 +548,25 @@ setMethod("[", "MsBackendDataFrame", function(x, i, j, ..., drop = FALSE) {
     .subset_backend_data_frame(x, i)
 })
 
+setClassUnion("dataframeOrDataFrameOrmatrix",
+              c("data.frame", "DataFrame", "matrix"))
+#' @exportMethod cbind2
+#'
+#' @importMethodsFrom methods cbind2
+#'
+#' @rdname hidden_aliases
+setMethod("cbind2", signature = c("MsBackendDataFrame",
+                                  "dataframeOrDataFrameOrmatrix"),
+          function(x, y = data.frame(), ...) {
+              if (is(y, "matrix"))
+                  y <- as.data.frame(y)
+              if (nrow(y) != length(x))
+                  stop("Length of 'y' does not match the number of spectra in 'x'")
+              x@spectraData <- cbind(x@spectraData, y)
+              validObject(x)
+              x
+          })
+
 #' @rdname hidden_aliases
 setMethod("split", "MsBackendDataFrame", function(x, f, drop = FALSE, ...) {
     if (!is.factor(f))

R/MsBackendMemory.R

@@ -651,6 +651,25 @@ setMethod("[", "MsBackendMemory", function(x, i, j, ..., drop = FALSE) {
     .df_subset(x, i)
 })
 
+setClassUnion("dataframeOrDataFrameOrmatrix",
+              c("data.frame", "DataFrame", "matrix"))
+#' @exportMethod cbind2
+#'
+#' @importMethodsFrom methods cbind2
+#'
+#' @rdname hidden_aliases
+setMethod("cbind2", signature = c("MsBackendMemory",
+                                  "dataframeOrDataFrameOrmatrix"),
+          function(x, y = data.frame(), ...) {
+              if (is(y, "matrix"))
+                  y <- as.data.frame(y)
+              if (nrow(y) != length(x))
+                  stop("Length of 'y' does not match the number of spectra in 'x'")
+              x@spectraData <- cbind(x@spectraData, y)
+              validObject(x)
+              x
+          })
+
 #' @rdname hidden_aliases
 setMethod("split", "MsBackendMemory", function(x, f, drop = FALSE, ...) {
     if (!is.factor(f))

R/Spectra.R

@@ -330,6 +330,15 @@ NULL
 #' - `[`: subsets the spectra keeping only selected elements (`i`). The method
 #'   **always** returns a `Spectra` object.
 #'
+#' - `cbind2()`: Appends multiple spectra variables from a `data.frame`,
+#'   `DataFrame` or `matrix` to the `Spectra`  object at once. It does so
+#'   *blindly* (e.g. do not check rownames compatibility) and is therefore at
+#'   the risk of the user. For a more  controlled way of adding spectra
+#'   variables, the `joinSpectraData()`  should be used. It will return a
+#'   `Spectra` object with the appended spectra variables. `cbind2()` does
+#'   check however that the number of rows of the `data.frame` or `DataFrame`
+#'   matches the number of spectra in the `Spectra` object.
+#'
 #' - `deisotopeSpectra()`: *deisotopes* each spectrum keeping only the
 #'   monoisotopic peak for groups of isotopologues. Isotopologues are
 #'   estimated using the [isotopologues()] function from the
@@ -533,6 +542,8 @@ NULL
 #'      should be explored and ideally be removed using for
 #'      `QFeatures::reduceDataFrame()`, `PMS::reducePSMs()` or similar
 #'      functions.
+#'     For a more general function that allows to append `data.frame`,
+#'     `DataFrame` and `matrix` see `cbind2()`.
 #'
 #' Several `Spectra` objects can be concatenated into a single object with the
 #' `c()` or the `concatenateSpectra()` function. Concatenation will fail if the
@@ -1088,7 +1099,9 @@ NULL
 #'
 #' @param x A `Spectra` object.
 #'
-#' @param y A `Spectra` object. A `DataFrame` for `joinSpectraData()`.
+#' @param y A `Spectra` object.
+#'     - For `joinSpectraData()`: a `DataFrame`.
+#'     - For `cbind2()` a `data.frame`, `DataFrame` or `matrix`.
 #'
 #' @param z For `filterPrecursorCharge()`: `integer()` with the precursor
 #'     charges to be used as filter.
@@ -1242,6 +1255,10 @@ NULL
 #' ## Subset to all MS2 spectra.
 #' data[msLevel(data) == 2]
 #'
+#' ## Append new `spectraVariables` to the `spectraData`
+#' df <- data.frame(cola = 4:5, colb = "b")
+#' data_append <- cbind2(data, df)
+#'
 #' ## Same with the filterMsLevel function
 #' filterMsLevel(data, 2)
 #'
@@ -2212,6 +2229,16 @@ setMethod("[", "Spectra", function(x, i, j, ..., drop = FALSE) {
     x
 })
 
+setClassUnion("dataframeOrDataFrame", c("data.frame", "DataFrame"))
+#' @rdname Spectra
+#'
+#' @export
+setMethod("cbind2", signature(x = "Spectra",
+                              y = "dataframeOrDataFrame"), function(x, y, ...) {
+                                  x@backend <- cbind2(x@backend, y, ...)
+                                  x
+                              })
+
 #' @rdname Spectra
 setMethod("filterAcquisitionNum", "Spectra", function(object, n = integer(),
                                                       dataStorage = character(),

inst/test_backends/test_MsBackend/test_spectra_subsetting.R

@@ -51,6 +51,19 @@ test_that("[", {
     expect_true(length(res) == 0L)
 })
 
+test_that("cbind2 works", {
+    seql <- length(be)
+    df <- data.frame(cola = seq_len(seql), colb = "b", colz = "z")
+    res <- cbind2(be, df)
+    expect_true(validObject(res))
+    expect_equal(ncol(spectraData(res)), length(spectraVariables(be)) + 3)
+    expect_equal(res$cola, seq_len(seql))
+    expect_equal(res$colb, rep("b", seql))
+    expect_equal(res$colz, rep("z", seql))
+    df2  <- data.frame(cola = 3:6, colb = "b", colz = "z")
+    expect_error(cbind2(be, df2), "does not match")
+})
+
 #' dropNASpectraVariables: only for not read-only
 #' core spectra variables don't get removed, even if only NA.
 test_that("dropNaSpectraVariables", {

tests/testthat/test_MsBackendDataFrame.R

@@ -613,6 +613,22 @@ test_that("[,MsBackendDataFrame works", {
     expect_equal(res@spectraData$file, c("b", "a"))
 })
 
+test_that("cbind2, MsBackendDataFrame works", {
+    be <- MsBackendDataFrame()
+    df <- DataFrame(scanIndex = 1:2, a = "a", b = "b")
+    be <- backendInitialize(be, df)
+    df2 <- data.frame(cola = 3:4, colb = "b", colz = "z")
+    res <- cbind2(be, df2)
+    expect_true(validObject(res))
+    expect_equal(ncol(spectraData(res)), ncol(spectraData(be)) +3)
+    expect_equal(res$cola, c(3, 4))
+    expect_equal(res$colb, c("b", "b"))
+    expect_equal(res$colz, c("z", "z"))
+    expect_equal(res$scanIndex, 1:2)
+    df3 <- data.frame(colv = 1:6, colw = "b")
+    expect_error(cbind2(be, df3), "does not match")
+})
+
 test_that("selectSpectraVariables,MsBackendDataFrame works", {
     be <- MsBackendDataFrame()
     res <- selectSpectraVariables(be, c("dataStorage", "msLevel"))