MSpectra {MSnbase} | R Documentation

## List of Spectrum objects along with annotations

### Description

`MSpectra` (Mass Spectra) objects allow to collect one or more Spectrum object(s) (Spectrum1 or Spectrum2) in a `list`-like structure with the possibility to add arbitrary annotations to each individual `Spectrum` object. These can be accessed/set with the `mcols()` method.

`MSpectra` objects can be created with the `MSpectra` function.

Functions to access the individual spectra's attributes are available (listed below).

`writeMgfData` exports a `MSpectra` object to a file in MGF format. All metadata columns present in `mcols` are exported as additional fields with the capitalized column names used as field names (see examples below).

### Usage

    MSpectra(..., elementMetadata = NULL)

    ## S4 method for signature 'MSpectra'
    mz(object)

    ## S4 method for signature 'MSpectra'
    intensity(object)

    ## S4 method for signature 'MSpectra'
    rtime(object)

    ## S4 method for signature 'MSpectra'
    precursorMz(object)

    ## S4 method for signature 'MSpectra'
    precursorCharge(object)

    ## S4 method for signature 'MSpectra'
    precScanNum(object)

    ## S4 method for signature 'MSpectra'
    precursorIntensity(object)

    ## S4 method for signature 'MSpectra'
    acquisitionNum(object)

    ## S4 method for signature 'MSpectra'
    scanIndex(object)

    ## S4 method for signature 'MSpectra,ANY'
    peaksCount(object)

    ## S4 method for signature 'MSpectra'
    msLevel(object)

    ## S4 method for signature 'MSpectra'
    tic(object)

    ## S4 method for signature 'MSpectra'
    ionCount(object)

    ## S4 method for signature 'MSpectra'
    collisionEnergy(object)

    ## S4 method for signature 'MSpectra'
    fromFile(object)

    ## S4 method for signature 'MSpectra'
    polarity(object)

    ## S4 method for signature 'MSpectra'
    smoothed(object)

    ## S4 method for signature 'MSpectra'
    isEmpty(x)

    ## S4 method for signature 'MSpectra'
    centroided(object)

    ## S4 method for signature 'MSpectra'
    isCentroided(object)

    ## S4 method for signature 'MSpectra'
    writeMgfData(object, con = "spectra.mgf", COM = NULL, TITLE = NULL)

    ## S4 method for signature 'MSpectra'
    clean(object, all = FALSE, msLevel. = msLevel., ...)

    ## S4 method for signature 'MSpectra'
    removePeaks(object, t, msLevel., ...)

    ## S4 method for signature 'MSpectra'
    filterMz(object, mz, msLevel., ...)

    ## S4 method for signature 'MSpectra'
    pickPeaks(
      object,
      halfWindowSize = 3L,
      method = c("MAD", "SuperSmoother"),
      SNR = 0L,
      refineMz = c("none", "kNeighbors", "kNeighbours", "descendPeak"),
      msLevel. = unique(msLevel(object)),
      ...
    )

    ## S4 method for signature 'MSpectra'
    smooth(
      x,
      method = c("SavitzkyGolay", "MovingAverage"),
      halfWindowSize = 2L,
      ...
    )

    ## S4 method for signature 'MSpectra'
    filterMsLevel(object, msLevel.)

### Arguments

`...` | For `MSpectra`: Spectrum object(s) or a `list` of Spectrum objects. For all other methods optional arguments passed along.
`elementMetadata` | For `MSpectra`: DataFrame with optional information that should be added as metadata information (`mcols`) to the object. The number of rows has to match the number of Spectrum objects, each row is expected to represent additional metadata information for one spectrum.
`object` | For all functions: a `MSpectra` object.
`x` | For all functions: a `MSpectra` object.
`con` | For `writeMgfData`: `character(1)` defining the file name of the MGF file.
`COM` | For `writeMgfData`: optional `character(1)` providing a comment to be added to the file.
`TITLE` | For `writeMgfData`: optional `character(1)` defining the title for the MGF file.
`all` | For `clean`: if `FALSE` original 0-intensity values are retained around peaks.
`msLevel.` | For `clean`, `removePeaks`, `filterMz`, `pickPeaks`: optionally specify the MS level(s) of the spectra on which the operation should be performed. For `filterMsLevels`: MS level(s) to which the `MSpectra` should be reduced.
`t` | For `removePeaks`: `numeric(1)` specifying the threshold below which intensities are set to 0.
`mz` | For `filterMz`: `numeric(2)` defining the lower and upper m/z for the filter. See `filterMz()` for details.
`halfWindowSize` | For `pickPeaks` and `smooth`: see `pickPeaks()` and `smooth()` for details.
`method` | For `pickPeaks` and `smooth`: see `pickPeaks()` and `smooth()` for details.
`SNR` | For `pickPeaks`: see `pickPeaks()` for details.
`refineMz` | For `pickPeaks`: see `pickPeaks()` for details.

### Details

`MSpectra` inherits all methods from the SimpleList class of the `S4Vectors` package. This includes `lapply` and other data manipulation and subsetting operations.

### Constructor

New MSpectra can be created with the `MSpectra(...)` function where `...` can either be a single Spectrum object or a `list` of `Spectrum` objects (Spectrum1 and/or Spectrum2).

### Accessing spectrum attributes

These methods allow to access the attributes and values of the individual `Spectrum` (Spectrum1 or Spectrum2) objects within the list.

- `mz` return the m/z values of each spectrum as a `list` of `numeric` vectors.

- `intensity` return the intensity values of each spectrum as a `list` of `numeric` vectors.

- `rtime` return the retention time of each spectrum as a `numeric` vector with length equal to the length of `object`.

- `precursorMz`, `precursorCharge`, `precursorIntensity`, `precScanNum` return precursor m/z values, charge, intensity and scan number for each spectrum as a `numeric` (or `integer`) vector with length equal to the length of `object`. Note that for Spectrum1 objects `NA` will be returned.

- `acquisitionNum` and `scanIndex` return the acquisition number of each spectrum and its scan index as an `integer` vector with the same length than `object`.

- `ionCount` and `tic` return the ion count and total ion current of each spectrum.

- `peaksCount` returns the number of peaks for each spectrum as a `integer` vector.

- `msLevel` returns the MS level of each spectrum.

- `collisionEnergy` returns the collision energy for each spectrum or `NA` for Spectrum1 objects.

- `polarity` returns the spectra's polarity.

- `fromFile` returns the index from the (e.g. mzML) file the spectra where from. This applies only for spectra read using the `readMSData()` function.

- `smoothed` whether spectra have been smoothed (i.e. processed with the `smooth()` method. Returns a `logical` of length equal to the number of spectra.

- `isEmpty` returns `TRUE` for spectra without peak data.

- `centroided`, `isCentroided` returns for each spectrum whether it contains centroided data. While `centroided` returns the internal attribute of each spectrum, `isCentroided` tries to guess whether spectra are centroided from the actual peak data.

### Data manipulation methods

- `clean` cleans each spectrum. See `clean()` for more details.

- `pickPeaks` performs peak picking to generate centroided spectra. See `pickPeaks()` for more details.

- `removePeaks` removes peaks lower than a threshold `t`. See `removePeaks()` for more details.

- `smooth` smooths spectra. See `smooth()` for more details.

### Filtering and subsetting

- `[` can be used to subset the `MSpectra` object.

- `filterMsLevel` filters `MSpectra` to retain only spectra from certain MS level(s).

- `filterMz` filters the spectra by the specified `mz` range. See `filterMz()` for details.

### Author(s)

Johannes Rainer

### Examples

    ## Create from Spectrum objects
    sp1 <- new("Spectrum1", mz = c(1, 2, 4), intensity = c(4, 5, 2))
    sp2 <- new("Spectrum2", mz = c(1, 2, 3, 4), intensity = c(5, 3, 2, 5),
        precursorMz = 2)

    spl <- MSpectra(sp1, sp2)
    spl
    spl[[1]]

    ## Add also metadata columns
    mcols(spl)$id <- c("a", "b")
    mcols(spl)

    ## Create a MSpectra with metadata
    spl <- MSpectra(sp1, sp2, elementMetadata = DataFrame(id = c("a", "b")))

    mcols(spl)
    mcols(spl)$id

    ## Extract the mz values for the individual spectra
    mz(spl)

    ## Extract the intensity values for the individual spectra
    intensity(spl)

    ## Extract the retention time values for the individual spectra
    rtime(spl)

    ## Extract the precursor m/z of each spectrum.
    precursorMz(spl)

    ## Extract the precursor charge of each spectrum.
    precursorCharge(spl)

    ## Extract the precursor scan number for each spectrum.
    precScanNum(spl)

    ## Extract the precursor intensity of each spectrum.
    precursorIntensity(spl)

    ## Extract the acquisition number of each spectrum.
    acquisitionNum(spl)

    ## Extract the scan index of each spectrum.
    scanIndex(spl)

    ## Get the number of peaks per spectrum.
    peaksCount(spl)

    ## Get the MS level of each spectrum.
    msLevel(spl)

    ## Get the total ion current for each spectrum.
    tic(spl)

    ## Get the total ion current for each spectrum.
    ionCount(spl)

    ## Extract the collision energy for each spectrum.
    collisionEnergy(spl)

    ## Extract the file index for each spectrum.
    fromFile(spl)

    ## Get the polarity for each spectrum.
    polarity(spl)

    ## Whether spectra are smoothed (i.e. processed with the `smooth`
    ## function).
    smoothed(spl)

    ## Are spectra empty (i.e. contain no peak data)?
    isEmpty(spl)

    ## Do the spectra contain centroided data?
    centroided(spl)

    ## Do the spectra contain centroided data? Whether spectra are centroided
    ## is estimated from the peak data.
    isCentroided(spl)

    ## Export the spectrum list to a MGF file. Values in metadata columns are
    ## exported as additional field for each spectrum.
    tmpf <- tempfile()
    writeMgfData(spl, tmpf)

    ## Evaluate the written output. The ID of each spectrum (defined in the
    ## "id" metadata column) is exported as field "ID".
    readLines(tmpf)

    ## Set mcols to NULL to avoid export of additional data fields.
    mcols(spl) <- NULL
    file.remove(tmpf)

    writeMgfData(spl, tmpf)
    readLines(tmpf)

    ## Filter the object by MS level
    filterMsLevel(spl, msLevel. = 1)

[Package MSnbase version 2.20.1 Index]