Merge pull request #20 from rformassspectrometry/jomain

feat: add MsBackendMetaboLights import/export

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: MsIO
 Title: Serializing and restoring/importing mass spectrometry data objects
-Version: 0.0.6
+Version: 0.0.7
 Authors@R:
     c(person(given = "Johannes", family = "Rainer",
              email = "[email protected]",
@@ -45,7 +45,8 @@ Suggests:
     xcms,
     alabaster.se,
     alabaster.matrix,
-    MsBackendMetaboLights,
+    MsBackendMetaboLights (>= 0.99.1),
+    BiocFileCache,
     QFeatures
 License: Artistic-2.0
 Encoding: UTF-8
@@ -61,6 +62,7 @@ Collate:
     'AllGenerics.R'
     'MetaboLightsParam.R'
     'MsBackend.R'
+    'MsBackendMetaboLights.R'
     'MsBackendMzR.R'
     'MsExperiment.R'
     'MsExperimentFiles.R'

NAMESPACE

@@ -26,6 +26,7 @@ importFrom(jsonlite,read_json)
 importFrom(jsonlite,serializeJSON)
 importFrom(jsonlite,unserializeJSON)
 importFrom(jsonlite,write_json)
+importFrom(methods,"slot<-")
 importFrom(methods,as)
 importFrom(methods,callNextMethod)
 importFrom(methods,existsMethod)

NEWS.md

@@ -1,5 +1,9 @@
 # Version 0.0
 
+## Changes in 0.0.7
+
+- Add `saveObject()` for `MsBackendMetaboLights`.
+
 ## Changes in 0.0.6
 
 - Expand unit tests.

R/AlabasterParam.R

@@ -27,8 +27,15 @@
 #'
 #' - `MsBackendMzR`, defined in the
 #'   [*Spectra*](https://bioconductor.org/packages/Spectra) package.
+#' - `MsBackendMetaboLights`, defined in the
+#'   [*MsBackendMetaboLights*](https://github.com/RforMassSpectrometry/MsBackendMetaboLights)
+#'   package.
 #' - `Spectra`, defined in the
 #'   [*Spectra*](https://bioconductor.org/packages/Spectra) package.
+#' - `MsExperiment`, defined in the
+#'   [*MsExperiment*](https://bioconductor.org/packages/MsExperiment) package.
+#' - `XcmsExperiment`, defined in the
+#'   [*xcms*](https://bioconductor.org/packages/xcms) package.
 #'
 #' In addition, the *MsIO* package defines the `AlabasterParam` which can be
 #' used to write or read MS objects using the `saveMsObject()` and
@@ -55,11 +62,17 @@
 #'     listed below.
 #'
 #' @param spectraPath For `readMsObject()`: `character(1)` optionally allowing
-#'   to define the (absolute) path where the spectra files (*data storage
-#'   files*) can be found. This parameter is used for `MsBackendMzR` (see
-#'   descriptions below) and can be passed through `...` also to
-#'   `readMsObject()` functions for other classes (such as `Spectra`,
-#'   `MsExperiment` etc).
+#'     to define the (absolute) path where the spectra files (*data storage
+#'     files*) can be found. This parameter is used for `MsBackendMzR` (see
+#'     descriptions below) and can be passed through `...` also to
+#'     `readMsObject()` functions for other classes (such as `Spectra`,
+#'     `MsExperiment` etc).
+#'
+#' @param offline For `readMsObject()` and `readObject()` to load MS data as a
+#'     `MsBackendMetaboLights()`: `logical(1)` to evaluate the local file cache
+#'     and only load local files. Thus `offline = TRUE` does not need an active
+#'     internet connection, but fails if one of more files are not cached
+#'     locally.
 #'
 #' @param ... optional additional parameters passed to the downstream
 #'     functions, such as for example `spectraPath` described above.
@@ -73,6 +86,7 @@
 #'     first parameter, from the specified path. `saveObject()` and
 #'     `saveMsObject()` don't return anything.
 #'
+#'
 #' @section On-disk storage for `MsBackendMzR` objects:
 #'
 #' `MsBackendMzR` objects can be exported or imported using the
@@ -94,6 +108,15 @@
 #' below for details.
 #'
 #'
+#' @section On-disk storage for `MsBackendMetaboLights` objects:
+#'
+#' The `MsBackendMetaboLights` extends the `MsBackendMzR` backend and hence the
+#' same files are stored. When a `MsBackendMetaboLights` object is restored,
+#' the `mtbls_sync()` function is called to check for presence of all MS data
+#' files and, if missing, re-download them from the *MetaboLights* repository
+#' (if parameter `offline = FALSE` is used).
+#'
+#'
 #' @section On-disk storage for `Spectra` objects:
 #'
 #' `Spectra` objects can be exported/imported using `saveMsObject()` and

R/MsBackendMetaboLights.R

@@ -0,0 +1,72 @@
+#' @rdname PlainTextParam
+setMethod("readMsObject", signature(object = "MsBackendMetaboLights",
+                                    param = "PlainTextParam"),
+          function(object, param, offline = FALSE) {
+              fl <- file.path(param@path, "ms_backend_data.txt")
+              if (!file.exists(fl))
+                  stop("No 'backend_data.txt' file found in the provided path.")
+              l2 <- readLines(fl, n = 2)
+              if (l2[1] != "# MsBackendMetaboLights")
+                  stop("Invalid class in 'ms_backend_data.txt' file.",
+                  "Should run with object = ", l2[1])
+              if (length(l2) > 1L) {
+                  data <- read.table(file = fl, sep = "\t", header = TRUE)
+                  rownames(data) <- NULL
+                  slot(object, "spectraData", check = FALSE) <- DataFrame(data)
+                  MsBackendMetaboLights::mtbls_sync(object, offline = offline)
+              }
+              validObject(object)
+              object
+          })
+
+################################################################################
+##
+## alabaster saveObject/readObject
+##
+################################################################################
+#' @rdname AlabasterParam
+setMethod("saveObject", "MsBackendMetaboLights", function(x, path, ...) {
+    .save_object_spectra_data(x, path, object = "ms_backend_metabo_lights")
+})
+
+#' @noRd
+#'
+#' @importFrom methods slot<-
+readAlabasterMsBackendMetaboLights <- function(path = character(),
+                                               metadata = list(),
+                                               offline = FALSE) {
+    if (!.is_spectra_installed())
+        stop("Required package 'Spectra' missing. Please install ",
+             "and try again.", call. = FALSE)
+    if (!.is_ms_backend_metabo_lights_installed())
+        stop("Required package 'MsBackendMetaboLights' missing. ",
+             "Please install and try again.", call. = FALSE)
+    validateAlabasterMsBackendMzR(path, metadata)
+    sdata <- altReadObject(file.path(path, "spectra_data"))
+    pvars <- altReadObject(file.path(path, "peaks_variables"))
+    be <- MsBackendMetaboLights::MsBackendMetaboLights()
+    slot(be, "spectraData", check = FALSE) <- sdata
+    slot(be, "peaksVariables", check = FALSE) <- pvars
+    MsBackendMetaboLights::mtbls_sync(be, offline = offline)
+    validObject(be)
+    be
+}
+
+#' @rdname AlabasterParam
+setMethod("saveMsObject", signature(object = "MsBackendMetaboLights",
+                                    param = "AlabasterParam"),
+          function(object, param) {
+              if (file.exists(param@path))
+                  stop("Overwriting or saving to an existing directory is not",
+                       " supported. Please remove the directory defined with",
+                       " parameter `path` first.")
+              saveObject(object, param@path)
+          })
+
+#' @rdname AlabasterParam
+setMethod("readMsObject", signature(object = "MsBackendMetaboLights",
+                                    param = "AlabasterParam"),
+          function(object, param, offline = FALSE) {
+              readAlabasterMsBackendMetaboLights(path = param@path,
+                                                 offline = offline)
+          })

R/MsBackendMzR.R

@@ -88,9 +88,14 @@ setMethod("readMsObject", signature(object = "MsBackendMzR",
 #'
 #' @rdname AlabasterParam
 setMethod("saveObject", "MsBackendMzR", function(x, path, ...) {
+    .save_object_spectra_data(x, path, object = "ms_backend_mz_r")
+})
+
+.save_object_spectra_data <- function(x, path, object, version = "1.0") {
     dir.create(path = path, recursive = TRUE, showWarnings = FALSE)
-    saveObjectFile(path, "ms_backend_mz_r",
-                   list(ms_backend_mz_r =list(version = "1.0")))
+    l <- list(list(version = version))
+    names(l) <- object
+    saveObjectFile(path, object, l)
     tryCatch({
         do.call(altSaveObject,
                 list(x = x@spectraData, path = file.path(path, "spectra_data")))
@@ -104,9 +109,9 @@ setMethod("saveObject", "MsBackendMzR", function(x, path, ...) {
                      path = file.path(path, "peaks_variables")))
     }, error = function(e) {
         stop("failed to save 'peaksVariables' of ", class(x)[1L], "\n - ",
-             e$message)
+             e$message, call. = FALSE)
     })
-})
+}
 
 #' @importFrom alabaster.base registerValidateObjectFunction
 #'

R/PlainTextParam.R

@@ -26,13 +26,16 @@
 #' are:
 #'
 #' - `MsBackendMzR` object, defined in the
-#'   ([Spectra](https://bioconductor.org/packages/Spectra)) package.
+#'   [*Spectra*](https://bioconductor.org/packages/Spectra) package.
+#' - `MsBackendMetaboLights` object, defined in the
+#'   [*MsBackendMetaboLights*](https://bioconductor.org/packages/MsBackendMetaboLights)
+#'   package.
 #' - `Spectra` object, defined in the
-#'   ([Spectra](https://bioconductor.org/packages/Spectra)) package.
+#'   [*Spectra*](https://bioconductor.org/packages/Spectra) package.
 #' - `MsExperiment` object, defined in the
-#'   ([MsExperiment](https://bioconductor.org/packages/MsExperiment)) package.
+#'   [*MsExperiment*](https://bioconductor.org/packages/MsExperiment) package.
 #' - `XcmsExperiment` object, defined in the
-#'   ([xcms](https://bioconductor.org/packages/xcms)) package.
+#'   [*xcms*](https://bioconductor.org/packages/xcms) package.
 #'
 #' See their respective section below for details and formats of the
 #' exported files.
@@ -48,6 +51,11 @@
 #'   `readMsObject()` functions for other classes (such as `Spectra`,
 #'   `MsExperiment` etc).
 #'
+#' @param offline For `readMsObject()` to load MS data as a
+#'   `MsBackendMetaboLights()`: `logical(1)` to evaluate **only** the local
+#'   file cache. Thus `offline = TRUE` does not need an active internet
+#'   connection, but fails if one of more files are not cached locally.
+#'
 #' @param ... Additional parameters passed down to internal functions. E.g.
 #'   parameter `spectraPath` (see above).
 #'
@@ -68,6 +76,15 @@
 #'   named *ms_backend_data.txt*. Each row of this tab-delimited text file
 #'   corresponds to a spectrum with its respective metadata in the columns.
 #'
+#'
+#' @section On-disk storage for `MsBackendMetaboLights` objects:
+#'
+#' The `MsBackendMetaboLights` extends the `MsBackendMzR` backend and hence the
+#' same files are stored. When a `MsBackendMetaboLights` object is restored,
+#' the `mtbls_sync()` function is called to check for presence of all MS data
+#' files and, if missing, re-download them from the *MetaboLights* repository.
+#'
+#'
 #' @section On-disk storage for `Spectra` objects:
 #'
 #' For `Spectra` objects, defined in the `Spectra` package, the files listed

R/zzz.R

@@ -3,6 +3,10 @@
     registerValidateObjectFunction("ms_backend_mz_r",
                                    validateAlabasterMsBackendMzR)
     registerReadObjectFunction("ms_backend_mz_r", readAlabasterMsBackendMzR)
+    registerValidateObjectFunction("ms_backend_metabo_lights",
+                                   validateAlabasterMsBackendMzR)
+    registerReadObjectFunction("ms_backend_metabo_lights",
+                               readAlabasterMsBackendMetaboLights)
     registerValidateObjectFunction("spectra", validateAlabasterSpectra)
     registerReadObjectFunction("spectra", readAlabasterSpectra)
     registerValidateObjectFunction("ms_experiment_files",