Suggested properties of implemented methods

To ensure consistency, the saveMsObject() should:

• first create the directory to which the data should be exported (defined by param path).
• throw an error if the directory exists or contains already an exported object (avoiding thus accidental overwriting and eventual data corruption/inconsistencies).

Both methods support also ..., hence, if needed, additional parameters can be added to an implementation of the generic method if needed.

library(MsStash)

PlainTextParam

Storage of MS data objects in plain text format aims to support an easy exchange of data, and in particular analysis results, with external software, such as MS-DIAL or mzmine3. In most cases, the data is stored as tabulator delimited text files simplifying the use of the data and results across multiple programming languages, or their import into spreadsheet applications. MS data objects stored in plain text format can also be fully re-imported into R providing thus an alternative, and more flexible, object serialization approach than the R internal Rds/RData format.

We implement a saveMsObject() method for our MySpectrum class and the PlainTextParam. This function first creates the required directory and throws an error if an result file is already stored there. Then it exports the data: for our example we store the data of the object into a single text file in a custom format we define: the metadata if first written to the file, one line per metadata item followed by the m/z and intensity values, each m/z-intensity pair in one line separated by a tabulator.

#' Write example class to a plain text file
setMethod("saveMsObject", signature(object = "MySpectrum",
                                    param = "PlainTextParam"),
          function(object, param) {
              dir.create(path = param@path, recursive = TRUE,
                         showWarnings = FALSE)
              fl <- file.path(param@path, "my_spectrum.txt")
              if (file.exists(fl))
                  stop("Overwriting an existing result object is not ",
                       "supported.")
              ## Write the type of object as a comment followed by the
              ## metadata.
              writeLines(c(paste0("# ", class(object)[1L]),
                           paste0("rtime:", object@rtime),
                           paste0("msl:", object@msl)), con = fl)
              ## Write the peak data, i.e. m/z and intensity values
              write.table(cbind(object@mz, object@intensity), file = fl,
                          sep = "\t", append = TRUE, col.names = FALSE,
                          row.names = FALSE)
          })

We next export our example object s with the saveMsData() method to a temporary folder.

p <- PlainTextParam(path = file.path(tempdir(), "text_format"))
saveMsObject(s, p)

The data was thus exported to this text file. The individual lines are:

readLines(file.path(p@path, "my_spectrum.txt"))

## [1] "# MySpectrum" "rtime:NA"     "msl:NA"       "1.4\t123.1"   "1.6\t1235.3" 
## [6] "1.9\t12.45"   "2.56\t51.5"

We next implement the readMsObject() method for this class. This function will read the text file content and assign the imported values to the different slots of the MySpectrum class.

#' Read example object from plain text file storage format
setMethod("readMsObject", signature(object = "MySpectrum",
                                    param = "PlainTextParam"),
          function(object, param) {
              fl <- file.path(param@path, "my_spectrum.txt")
              if (!file.exists(fl))
                  stop("my_spectrum.txt not found in the provided path")
              l <- readLines(fl, n = 3) # read the comment and the metadata
              p <- read.table(fl, sep = "\t", skip = 3)
              MySpectrum(
                  mz = p[, 1L], intensity = p[, 2L],
                  rtime = suppressWarnings(
                      as.numeric(sub("rtime:", "", l[2], fixed = TRUE))),
                  msl = suppressWarnings(
                      as.integer(sub("msl:", "", l[3], fixed = TRUE))))
          })

We can now restore our MySpectrum object with the readMsObject() method from the exported text file:

p <- PlainTextParam(path = file.path(tempdir(), "text_format"))
b <- readMsObject(MySpectrum(), p)
b

## An object of class "MySpectrum"
## Slot "mz":
## [1] 1.40 1.60 1.90 2.56
## 
## Slot "intensity":
## [1]  123.10 1235.30   12.45   51.50
## 
## Slot "rtime":
## [1] NA
## 
## Slot "msl":
## [1] NA

AlabasterParam

The alabaster framework and related Bioconductor package alabaster.base implements methods to save a variety of R/Bioconductor objects to on-disk representations based on standard file formats like HDF5 and JSON. This ensures that Bioconductor objects can be easily read from other languages like Python and Javascript. With AlabasterParam, MsStash provides a parameter class to configure saving MS data objects in the alabaster storage format.

To enable writing in this format a saveMsObject() method should be implemented for the MS data object and AlabasterParam. To enable full alabaster support it is also suggested to implement the alabaster.base::saveObject method, a validation method and a function to read from an alabaster format. For more details refer also to the package vignette of the alabaster.base package, in particular chapter 5 Extending to new classes.

We below define a saveObject() method. The generic for this method is defined in the alabaster.base package. While it would be possible to simply save the data as simple text files as we did above, we use alabaster’s strategy to allow storage of more complex objects (such as S4 objects in the individual slots). This uses altSaveObject() and altReadObject() to save individual slots or parent/child classes in sub-directories of path. For each of these classes, a saveObject() needs to be defined.

library(alabaster.base)

setMethod("saveObject", "MySpectrum", function(x, path, ...) {
    ## Create the directory where to save the data
    dir.create(path = path, recursive = TRUE, showWarnings = FALSE)
    ## Create an "object" file; this defines the type of object stored in path
    saveObjectFile(path, "my_spectrum")
    ## save each slot into it's own directory
    altSaveObject(x@mz, path = file.path(path, "mz"))
    altSaveObject(x@intensity, path = file.path(path, "intensity"))
    altSaveObject(x@rtime, path = file.path(path, "retention_time"))
    altSaveObject(x@msl, path = file.path(path, "ms_level"))
})

We next need to implement a validation function for the stash (directory). For our example we simply check that the path contains the expected sub-directories with the object’s content. This function needs then to be registered with the registerValidateObjectFunction() method for our class.

#' Define a helper function to check that the folder contains all
#' expected sub-directories.
validateMySpectrum <- function(path, metadata) {
    if (!dir.exists(path))
        stop("Directory ", path, " does not exist")
    req_dir <- c("mz", "intensity", "retention_time", "ms_level")
    if (any(miss <- !dir.exists(file.path(path, req_dir))))
        stop("Required directories ",
             paste0("\"", req_dir[miss], "\"", collapse = ", "),
             " not found in ", path)
}

#' Register the validation function
registerValidateObjectFunction("my_spectrum", validateMySpectrum)

## NULL

Finally we define the function to read the data back from the stash. We then register this function with alabaster’s registerReadObjectFunction() function.

#' Define a function that can read from an alabaster-based serialization
#' of `MySpectrum` objects
readMySpectrum <- function(path, metadata, ...) {
    validateMySpectrum(path)
    ## Read the data from individual sub-directories
    mz <- altReadObject(file.path(path, "mz"))
    int <- altReadObject(file.path(path, "intensity"))
    rtime <- altReadObject(file.path(path, "retention_time"))
    msl <- altReadObject(file.path(path, "ms_level"))
    MySpectrum(mz = mz, intensity = int, rtime = rtime, msl = msl)
}

#' Register the read function
registerReadObjectFunction("my_spectrum", readMySpectrum)

Registration of the validation and read functions is generally done in the extension package’s onLoad() function.

With these functions defined and registered, we can store an instance of MySpectrum directly with alabaster’s saveObject() method:

#' Define the path where we want to export out data
p <- file.path(tempdir(), "alabaster_export")

#' Save the object
saveObject(s, path = p)

This saved the object’s content to the directory specified with path. The content of this folder is:

library(fs)
dir_tree(p)

## /tmp/RtmpxcIktN/alabaster_export
## ├── OBJECT
## ├── _environment.json
## ├── intensity
## │   ├── OBJECT
## │   └── contents.h5
## ├── ms_level
## │   ├── OBJECT
## │   └── contents.h5
## ├── mz
## │   ├── OBJECT
## │   └── contents.h5
## └── retention_time
##     ├── OBJECT
##     └── contents.h5

We can read the serialized object again as a MySpectrum object:

b <- readObject(p)
b

## An object of class "MySpectrum"
## Slot "mz":
## [1] 1.40 1.60 1.90 2.56
## 
## Slot "intensity":
## [1]  123.10 1235.30   12.45   51.50
## 
## Slot "rtime":
## [1] NA
## 
## Slot "msl":
## [1] NA

We next implement the saveMsObject() and readMsObject() methods for MySpectrum and AlabasterParam. These can simply re-use the functions implemented above.

#' Write example class to a plain text file
setMethod("saveMsObject", signature(object = "MySpectrum",
                                    param = "AlabasterParam"),
          function(object, param) {
              if (file.exists(file.path(param@path, "OBJECT")))
                  stop("'path' contains already an MS data stash. Overwriting",
                       " is not supported. Please remove 'path' first.")
              saveObject(object, param@path)
          })

#' Read example object from plain text file storage format
setMethod("readMsObject", signature(object = "MySpectrum",
                                    param = "AlabasterParam"),
          function(object, param) {
              readMySpectrum(param@path)
          })

We can now stash our MS object in either the text file-based format (PlainTextParam) or the alabaster-based format (AlabasterParam). Below we write it using the alabaster approach.

p <- file.path(tempdir(), "alabaster_format_2")
ap <- AlabasterParam(p)

saveMsObject(s, ap)

To read the data back we can then use readMsObject() specifying in addition the type of object we want to read.

b <- readMsObject(MySpectrum(), ap)
b

## An object of class "MySpectrum"
## Slot "mz":
## [1] 1.40 1.60 1.90 2.56
## 
## Slot "intensity":
## [1]  123.10 1235.30   12.45   51.50
## 
## Slot "rtime":
## [1] NA
## 
## Slot "msl":
## [1] NA