OnDiskMSnExp-class {MSnbase} | R Documentation

## The `OnDiskMSnExp` Class for MS Data And Meta-Data

### Description

Like the `MSnExp` class, the `OnDiskMSnExp` class encapsulates data and meta-data for mass spectrometry experiments, but does, in contrast to the former, not keep the spectrum data in memory, but fetches the M/Z and intensity values on demand from the raw files. This results in some instances to a reduced performance, has however the advantage of a much smaller memory footprint.

### Details

The `OnDiskMSnExp` object stores many spectrum related information into the `featureData`, thus, some calls, like `rtime` to retrieve the retention time of the individual scans does not require the raw data to be read. Only M/Z and intensity values are loaded on-the-fly from the original files. Extraction of values for individual scans is, for mzML files, very fast. Extraction of the full data (all spectra) are performed in a per-file parallel processing strategy.

Data manipulations related to spectras' M/Z or intensity values (e.g. `removePeaks` or `clean`) are (for `OnDiskMSnExp` objects) not applied immediately, but are stored for later execution into the `spectraProcessingQueue`. The manipulations are performed on-the-fly upon data retrieval. Other manipulations, like removal of individual spectra are applied directly, since the corresponding data is available in the object's `featureData` slot.

### Objects from the Class

Objects can be created by calls of the form `new("OnDiskMSnExp",...)`. However, it is preferred to use the `readMSData` function with argument `backend="disk"` that will read raw mass spectrometry data to generate a valid `"OnDiskMSnExp"` instance.

### Slots

`backend`:

  Character string specifying the used backend.

`spectraProcessingQueue`:

  `list` of `ProcessingStep` objects defining the functions to be applied on-the-fly to the spectra data (M/Z and intensity duplets).

`assayData`:

  Object of class `"environment"` that is however empty, as no spectrum data is stored. Slot is inherited from `"pSet"`.

`phenoData`:

  Object of class `"AnnotatedDataFrame"` containing experimenter-supplied variables describing sample (i.e the individual tags for an labelled MS experiment) See `phenoData` for more details. Slot is inherited from `"pSet"`.

`featureData`:

  Object of class `"AnnotatedDataFrame"` containing variables describing features (spectra in our case). See `featureData` for more details. Slot is inherited from `"pSet"`.

`experimentData`:

  Object of class `"MIAPE"`, containing details of experimental methods. See `experimentData` for more details. Slot is inherited from `"pSet"`.

`protocolData`:

  Object of class `"AnnotatedDataFrame"` containing equipment-generated variables (inherited from `"eSet"`). See `protocolData` for more details. Slot is inherited from `"pSet"`.

`processingData`:

  Object of class `"MSnProcess"` that records all processing. Slot is inherited from `"pSet"`.

`.__classVersion__`:

  Object of class `"Versions"` describing the versions of R, the Biobase package, `"pSet"` and `MSnExp` of the current instance. Slot is inherited from `"pSet"`. Intended for developer use and debugging (inherited from `"eSet"`).

### Extends

Class `"MSnExp"`, directly. Class `"pSet"`, by class "MSnExp", distance 3. Class `"VersionedBiobase"`, by class "pSet", distance 4. Class `"Versioned"`, by class "pSet", distance 5.

### Getter/setter methods

(in alphabetical order) See also methods for `MSnExp` or `pSet` objects.

[

  `object[i]`:subset the `OnDiskMSnExp` by spectra. `i` can be a `numeric` or `logical` vector specifying to which spectra the data set should be reduced (with `i` being the index of the spectrum in the object's `featureData`).

  The method returns a `OnDiskMSnExp` object with the data sub-set.

[[

  `object[[i]]`: extract s single spectrum from the `OnDiskMSnExp` object `object`. Argument `i` can be either numeric or character specifying the index or the name of the spectrum in the object (i.e. in the `featureData`). The relevant information will be extracted from the corresponding raw data file.

  The method returns a `Spectrum1` object.

acquisitionNum

  `acquisitionNum(signature(object="OnDiskMSnExp"))`: get the acquisition number of each spectrum in each individual file. The relevant information is extracted from the object's `featureData` slot.

  Returns a numeric vector with names corresponding to the spectrum names.

assayData

  `assayData(signature(object = "OnDiskMSnExp"))`: Extract the full data, i.e. read all spectra from the original files, apply all processing steps from the `spectraProcessingQueue` slot and return the data. Due to the required processing time accessing the full data should be avoided wherever possible.

  Returns an `environment`.

centroided,centroided<-

  `centroided(signature(object="OnDiskMSnExp", msLevel, = "numeric"))`: whether individual spectra are centroided or uncentroided. The relevant information is extracted from the object's `featureData` slot. Returns a logical vector with names corresponding to the spectrum names. Use `centroided(object) <- value` to update the information, with value being a logical vector of length equal to the number of spectra in the experiment.

`isCentroided(object, k = 0.025, qtl = 0.9, verbose = TRUE)`

  A heuristic assessing if the spectra in the `object` are in profile or centroided mode. The function takes the `qtl`th quantile top peaks, then calculates the difference between adjacent M/Z value and returns `TRUE` if the first quartile is greater than `k`. (See `MSnbase:::.isCentroided` for the code.) If `verbose` (default), a table indicating mode for all MS levels is printed.

  The function has been tuned to work for MS1 and MS2 spectra and data centroided using different peak picking algorithms, but false positives can occur. See https://github.com/lgatto/MSnbase/issues/131 for details. For whole experiments, where all MS1 and MS2 spectra are expected to be in the same, albeit possibly different modes, it is advised to assign the majority result for MS1 and MS2 spectra, rather than results for individual spectra.

  See also `isCentroidedFromFile` that accessed the mode directly from the raw data file.

fromFile

  `fromFile(signature(object = "OnDiskMSnExp"))`: get the index of the file (in `fileNames(object)`) from which the spectra were read. The relevant information is extracted from the object's `featureData` slot.

  Returns a numeric vector with names corresponding to the spectrum names.

intensity

  `intensity(signature(object="OnDiskMSnExp"))`: return the intensities from each spectrum in the data set. Intensities are first read from the raw files followed by an optional processing (depending on the processing steps defined in the `spectraProcessingQueue`). To reduce the amount of required memory, this is performed on a per-file basis. The `BPPARAM` argument allows to specify how and if parallel processing should be used. Information from individual files will be processed in parallel (one process per original file).

  The method returns a `list` of numeric intensity values. Each list element represents the intensities from one spectrum.

ionCount

  `ionCount(signature(object="OnDiskMSnExp", BPPARAM=bpparam()))`: extract the ion count (i.e. sum of intensity values) for each spectrum in the data set. The relevant data has to be extracted from the raw files (with eventually applying processing steps). The `BPPARAM` argument can be used to define how and if parallel processing should be used. Information from individual files will be processed in parallel (one process per original file).

  Returns a numeric vector with names corresponding to the spectrum names.

isolationWindowLowerMz

  `isolationWindowLowerMz(object = "OnDiskMSnExp")`: return the lower m/z boundary for the isolation window.

  Returns a numeric vector of length equal to the number of spectra with the lower m/z value of the isolation window or `NA` if not specified in the original file.

isolationWindowUpperMz

  `isolationWindowUpperMz(object = "OnDiskMSnExp")`: return the upper m/z boundary for the isolation window.

  Returns a numeric vector of length equal to the number of spectra with the upper m/z value of the isolation window or `NA` if not specified in the original file.

length

  `length(signature(object="OnDiskMSnExp"))`: Returns the number of spectra of the current experiment.

msLevel

  `msLevel(signature(object = "OnDiskMSnExp"))`: extract the MS level from the spectra. The relevant information is extracted from the object's `featureData` slot.

  Returns a numeric vector with names corresponding to the spectrum names.

mz

  `mz(signature(object="OnDiskMSnExp"))`: return the M/Z values from each spectrum in the data set. M/Z values are first read from the raw files followed by an optional processing (depending on the processing steps defined in the `spectraProcessingQueue`). To reduce the amount of required memory, this is performed on a per-file basis. The `BPPARAM` argument allows to specify how and if parallel processing should be used. Information from individual files will be processed in parallel (one process per original file).

  The method returns a `list` of numeric M/Z values. Each list element represents the values from one spectrum.

peaksCount

  `peaksCount(signature(object="OnDiskMSnExp", scans="numeric"), BPPARAM=bpparam())`: extrac the peaks count from each spectrum in the object. Depending on the eventually present `ProcessingStep` objects in the `spectraProcessingQueue` raw data will be loaded to calculate the peaks count. If no steps are present, the data is extracted from the `featureData`. Optional argument `scans` allows to specify the index of specific spectra from which the count should be returned. The `BPPARAM` argument can be used to define how and if parallel processing should be used. Information from individual files will be processed in parallel (one process per original file).

  Returns a numeric vector with names corresponding to the spectrum names.

polarity

  `polarity(signature(object="OnDiskMSnExp"))`: returns a numeric vector with the polarity of the individual spectra in the data set. The relevant information is extracted from the `featureData`.

rtime

  `rtime(signature(object="OnDiskMSnExp"))`: extrac the retention time of the individual spectra in the data set (from the `featureData`).

  Returns a numeric vector with names corresponding to the spectrum names.

scanIndex

  `scanIndex(signature(object="OnDiskMSnExp"))`: get the spectra scan indices within the respective file. The relevant information is extracted from the object's `featureData` slot. Returns a numeric vector of indices with names corresponding to the spectrum names.

smoothed,smoothed<-

  `smoothed(signature(object="OnDiskMSnExp", msLevel. = "numeric"))`: whether individual spectra are smoothed or unsmoothed. The relevant information is extracted from the object's `featureData` slot. Returns a logical vector with names corresponding to the spectrum names. Use `smoothed(object) <- value` to update the information, with value being a logical vector of length equal to the number of spectra in the experiment.

spectra

  `spectra(signature(object="OnDiskMSnExp"), BPPARAM=bpparam())`: extract spectrum data from the individual files. This causes the spectrum data to be read from the original raw files. After that all processing steps defined in the `spectraProcessingQueue` are applied to it. The results are then returned as a `list` of `Spectrum1` objects.

  The `BPPARAM` argument can be used to define how and if parallel processing should be used. Information from individual files will be processed in parallel (one process per file). Note: extraction of selected spectra results in a considerable processing speed and should thus be preferred over whole data extraction.

  Returns a `list` of `Spectrum1` objects with names corresponding to the spectrum names.

tic

  `tic(signature(object="OnDiskMSnExp"), initial = TRUE, BPPARAM = bpparam())`: get the total ion current (TIC) of each spectrum in the data set. If `initial = TRUE`, the information is extracted from the object's `featureData` and represents the tic provided in the header of the original raw data files. For `initial = FALSE`, the TIC is calculated from the actual intensity values in each spectrum after applying all eventual data manipulation methods.

  See also https://github.com/lgatto/MSnbase/issues/332 for more details.

  `BPPARAM` parameter: see `spectra` method above.

  Returns a numeric vector with names corresponding to the spectrum names.

bpi

  `bpi(signature(object="OnDiskMSnExp"), initial = TRUE, BPPARAM = bpparam())`: get the base peak intensity (BPI), i.e. the maximum intensity from each spectrum in the data set. If `initial = TRUE`, the information is extracted from the object's `featureData` and represents the bpi provided in the header of the original raw data files. For `initial = FALSE`, the BPI is calculated from the actual intensity values in each spectrum after applying all eventual data manipulation methods.

  See also https://github.com/lgatto/MSnbase/issues/332 for more details.

  `BPPARAM` parameter: see `spectra` method above.

  Returns a numeric vector with names corresponding to the spectrum names.

featureNames

  `tic(signature(object="OnDiskMSnExp"))`: return a `character` of length `length(object)` containing the feature names. A replacement method is also available.

spectrapply

  `spectrapply(signature(object = "OnDiskMSnExp"), FUN = NULL, BPPARAM = bpparam(), ...)`: applies the function `FUN` to each spectrum passing additional parameters in `...` to that function and return its results. For `FUN = NULL` it returns the list of spectra (same as a call to `spectra`). Parameter `BPPARAM` allows to specify how and if parallel processing should be enabled.

  Returns a list with the result for each of spectrum.

### Data manipulation methods

(in alphabetical order) See also methods for `MSnExp` or `pSet` objects. In contrast to the same-named methods for `pSet` or `MSnExp` classes, the actual data manipulation is not performed immediately, but only on-demand, e.g. when intensity or M/Z values are loaded.

clean

  `clean(signature(object="OnDiskMSnExp"), all=TRUE, verbose=TRUE)`: add an clean processing step to the lazy processing queue of the `OnDiskMSnExp` object. The `clean` command will only be executed when spectra information (including M/Z and intensity values) is requested from the `OnDiskMSnExp` object. Optional arguments to the methods are `all=TRUE` and `verbose=TRUE`.

  The method returns an `OnDiskMSnExp` object.

  For more details see documentation of the `clean` method.

normalize

  `normalize(signature(object="OnDiskMSnExp"), method=c("max", "sum"), ...)`: add a `normalize` processing step to the lazy processing queue of the returned `OnDiskMSnExp` object.

  The method returns an `OnDiskMSnExp` object.

  For more details see documentation of the `normalize` method.

removePeaks

  `removePeaks(signature(object="OnDiskMSnExp"), t="min", verbose=TRUE)`: add a `removePeaks` processing step to the lazy processing queue of the returned `OnDiskMSnExp` object.

  The method returns an `OnDiskMSnExp` object.

  For more details see documentation of the `removePeaks` method.

trimMz

  `trimMz(signature(object="OnDiskMSnExp", mzlim="numeric"),...)`: add a `trimMz` processing step to the lazy processing queue of the returned `OnDiskMSnExp` object.

  The method returns an `OnDiskMSnExp` object.

  For more details see documentation of the `trimMz` method.

### Other methods and functions

validateOnDiskMSnExp

  `validateOnDiskMSnExp(signature(object = "OnDiskMSnExp"))`: validates an `OnDiskMSnExp` object and all of its spectra. In addition to the standard `validObject` method, this method reads also all spectra from the original files, applies eventual processing steps and evaluates their validity.

`as(from, "MSnExp")`

  Converts the `OnDiskMSnExp` object `from`, to an in-memory `MSnExp`. Also available as an S3 method `as.MSnExp()`.

### Author(s)

Johannes Rainer <johannes.rainer@eurac.edu>

### See Also

`pSet`, `MSnExp`, `readMSData`

### Examples

    ## Get some example mzML files
    library(msdata)
    mzfiles <- c(system.file("microtofq/MM14.mzML", package="msdata"),
    	     system.file("microtofq/MM8.mzML", package="msdata"))
    ## Read the data as an OnDiskMSnExp
    odmse <- readMSData(mzfiles, msLevel=1, centroided = TRUE)

    ## Get the length of data, i.e. the total number of spectra.
    length(odmse)

    ## Get the MS level
    head(msLevel(odmse))

    ## Get the featureData, use fData to return as a data.frame
    head(fData(odmse))

    ## Get to know from which file the spectra are
    head(fromFile(odmse))

    ## And the file names:
    fileNames(odmse)

    ## Scan index and acquisitionNum
    head(scanIndex(odmse))
    head(acquisitionNum(odmse))

    ## Extract the spectra; the data is retrieved from the raw files.
    head(spectra(odmse))

    ## Extracting individual spectra or a subset is much faster.
    spectra(odmse[1:50])

    ## Alternatively, we could also subset the whole object by spectra and/or samples:
    subs <- odmse[rtime(odmse) >= 2 & rtime(odmse) <= 20, ]
    fileNames(subs)
    rtime(subs)

    ## Extract intensities and M/Z values per spectrum; the methods return a list,
    ## each element representing the values for one spectrum.
    ints <- intensity(odmse)
    mzs <- mz(odmse)

    ## Return a data.frame with mz and intensity pairs for each spectrum from the
    ## object
    res <- spectrapply(odmse, FUN = as, Class = "data.frame")

    ## Calling removePeaks, i.e. setting intensity values below a certain threshold to 0.
    ## Unlike the name suggests, this is not actually removing peaks. Such peaks with a 0
    ## intensity are then removed by the "clean" step.
    ## Also, the manipulations are not applied directly, but put into the "lazy"
    ## processing queue.
    odmse <- removePeaks(odmse, t=10000)
    odmse <- clean(odmse)

    ## The processing steps are only applied when actual raw data is extracted.
    spectra(odmse[1:2])

    ## Get the polarity of the spectra.
    head(polarity(odmse))

    ## Get the retention time of all spectra
    head(rtime(odmse))

    ## Get the intensities after removePeaks and clean
    intsAfter <- intensity(odmse)

    head(lengths(ints))
    head(lengths(intsAfter))

    ## The same for the M/Z values
    mzsAfter <- intensity(odmse)
    head(lengths(mzs))
    head(lengths(mzsAfter))

    ## Centroided or profile mode
    f <- msdata::proteomics(full.names = TRUE,
    			pattern = "MS3TMT11.mzML")
    odmse <- readMSData(f, mode = "onDisk")
    validObject(odmse)
    odmse[[1]]

    table(isCentroidedFromFile(odmse), msLevel(odmse))

    ## centroided status could be set manually
    centroided(odmse, msLevel = 1) <- FALSE
    centroided(odmse, msLevel = 2) <- TRUE
    centroided(odmse, msLevel = 3) <- TRUE

    ## or when reading the data
    odmse2 <- readMSData(f, centroided = c(FALSE, TRUE, TRUE),
    		     mode = "onDisk")
    table(centroided(odmse), msLevel(odmse))

    ## Filtering precursor scans

    head(acquisitionNum(odmse))
    head(msLevel(odmse))

    ## Extract all spectra stemming from the first MS1 spectrum
    (from1 <- filterPrecursorScan(odmse, 21945))
    table(msLevel(from1))

    ## Extract the second sepctrum's parent (MS1) and children (MS3)
    ## spectra
    (from2 <- filterPrecursorScan(odmse, 21946))
    table(msLevel(from2))

[Package MSnbase version 2.12.0 Index]