OnDiskMSnExp-class: The 'OnDiskMSnExp' Class for MS Data And Meta-Data

In lgatto/MSnbase: Base Functions and Classes for Mass Spectrometry and Proteomics

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 qtlth 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 data manipulation methods (if any).

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 <[e-mail]>

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

lgatto/MSnbase documentation built on Nov. 12, 2024, 10:58 a.m.