Adds asDataFrame() function (close #325)

DESCRIPTION

@@ -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

@@ -8,6 +8,7 @@ export(MsBackendMemory)
 export(MsBackendMzR)
 export(PrecursorMzParam)
 export(applyProcessing)
+export(asDataFrame)
 export(chunkapply)
 export(combinePeaksData)
 export(combineSpectra)

NEWS.md

@@ -6,6 +6,8 @@
   *MetaboCoreUtils* directly through their namespace (`MsCoreUtils::`) to avoid
   errors if performed in parallel on Windows machines or if called on a
   re-loaded object.
+- New `asDataFrame()` function to convert a (small) `Spectra` object
+  into a long `DataFrame`.
 
 ## Changes in 1.15.2
 

R/Spectra.R

@@ -898,7 +898,9 @@ NULL
 #'       window left and right of a peak where to remove fourier transform
 #'       artefacts.
 #'
-#' @param i For `[`: `integer`, `logical` or `character` to subset the object.
+#' @param i For `[`: `integer`, `logical` or `character` to subset the
+#'     object. For `asDataFrame()` an `numeric` indicating which scans to coerce
+#'     to a `DataFrame` (default is `seq_along(object)`).
 #'
 #' @param j For `[`: not supported.
 #'
@@ -2831,3 +2833,24 @@ setReplaceMethod("dataStorageBasePath", "Spectra", function(object, value) {
     dataStorageBasePath(object@backend) <- value
     object
 })
+
+#' @export
+#' @rdname Spectra
+#'
+#' @param spectraVars `character()` indicating what spectra variables to add to
+#'     the `DataFrame`. Default is `spectraVariables(object)`, i.e. all
+#'     available variables.
+#'
+#' @examples
+#'
+#' ## Convert a subset of the Spectra object to a long DataFrame.
+#' asDataFrame(sciex, i = 1:3, spectraVars = c("rtime", "msLevel"))
+asDataFrame <- function(object, i = seq_along(object),
+                        spectraVars = spectraVariables(object)) {
+    stopifnot(inherits(object, "Spectra"))
+    object <- object[i]
+    n <- sapply(peaksData(object), nrow)
+    v <- spectraData(object)[rep(seq_along(object), n), spectraVars]
+    p <- do.call(rbind, as.list(peaksData(object)))
+    cbind(p, v)
+}

tests/testthat/test_Spectra.R

@@ -1908,3 +1908,24 @@ test_that("dataStorageBasePath,dataStorageBasePath<-,MsBackendMzR works", {
     #' errors
     expect_error(dataStorageBasePath(tmp) <- "some path", "Provided path")
 })
+
+
+test_that("asDataFrame works", {
+    sciex_file <- normalizePath(
+        dir(system.file("sciex", package = "msdata"), full.names = TRUE))
+    sp <- Spectra(sciex_file)
+    ## Full dataframe
+    df <- asDataFrame(sp)
+    expect_identical(nrow(df), sum(sapply(peaksData(sp), nrow)))
+    expect_identical(ncol(df), length(spectraVariables(sp)) + 2L)
+    expect_identical(names(df), c("mz", "intensity", spectraVariables(sp)))
+    ## Three first scans and 2 spectra variables
+    df <- asDataFrame(sp, i = 1:3, spectraVars = c("msLevel", "rtime"))
+    expect_identical(nrow(df), sum(sapply(peaksData(sp[1:3]), nrow)))
+    expect_identical(ncol(df), 2L + 2L)
+    ## Three first scans and no spectra variables
+    df <- asDataFrame(sp, i = 1:3, spectraVars = NULL)
+    expect_identical(nrow(df), sum(sapply(peaksData(sp[1:3]), nrow)))
+    expect_identical(ncol(df), 2L)
+    expect_identical(names(df), c("mz", "intensity"))
+})