R/DataClasses.R
, R/functions-MSpectra.R
, R/methods-MSpectra.R
MSpectra.Rd
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).
MSpectra(..., elementMetadata = NULL)
# S4 method for MSpectra
mz(object)
# S4 method for MSpectra
intensity(object)
# S4 method for MSpectra
rtime(object)
# S4 method for MSpectra
precursorMz(object)
# S4 method for MSpectra
precursorCharge(object)
# S4 method for MSpectra
precScanNum(object)
# S4 method for MSpectra
precursorIntensity(object)
# S4 method for MSpectra
acquisitionNum(object)
# S4 method for MSpectra
scanIndex(object)
# S4 method for MSpectra,ANY
peaksCount(object)
# S4 method for MSpectra
msLevel(object)
# S4 method for MSpectra
tic(object)
# S4 method for MSpectra
ionCount(object)
# S4 method for MSpectra
collisionEnergy(object)
# S4 method for MSpectra
fromFile(object)
# S4 method for MSpectra
polarity(object)
# S4 method for MSpectra
smoothed(object)
# S4 method for MSpectra
isEmpty(x)
# S4 method for MSpectra
centroided(object)
# S4 method for MSpectra
isCentroided(object)
# S4 method for MSpectra
writeMgfData(object, con = "spectra.mgf", COM = NULL, TITLE = NULL)
# S4 method for MSpectra
clean(object, all = FALSE, msLevel. = msLevel., ...)
# S4 method for MSpectra
removePeaks(object, t, msLevel., ...)
# S4 method for MSpectra
filterMz(object, mz, msLevel., ...)
# S4 method for MSpectra
pickPeaks(
object,
halfWindowSize = 3L,
method = c("MAD", "SuperSmoother"),
SNR = 0L,
refineMz = c("none", "kNeighbors", "kNeighbours", "descendPeak"),
msLevel. = unique(msLevel(object)),
...
)
# S4 method for MSpectra
smooth(
x,
method = c("SavitzkyGolay", "MovingAverage"),
halfWindowSize = 2L,
...
)
# S4 method for MSpectra
filterMsLevel(object, msLevel.)
For MSpectra
: Spectrum object(s) or a list
of
Spectrum objects.
For all other methods optional arguments passed along.
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.
For all functions: a MSpectra
object.
For all functions: a MSpectra
object.
For writeMgfData
: character(1)
defining the file name of
the MGF file.
For writeMgfData
: optional character(1)
providing a comment
to be added to the file.
For writeMgfData
: optional character(1)
defining the title
for the MGF file.
For clean
: if FALSE
original 0-intensity values are retained
around peaks.
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.
For removePeaks
: numeric(1)
specifying the threshold below
which intensities are set to 0.
For filterMz
: numeric(2)
defining the lower and upper m/z
for the filter. See filterMz()
for details.
For pickPeaks
and smooth
: see pickPeaks()
and smooth()
for details.
For pickPeaks
and smooth
: see pickPeaks()
and smooth()
for details.
For pickPeaks
: see pickPeaks()
for details.
For pickPeaks
: see pickPeaks()
for details.
MSpectra
inherits all methods from the SimpleList class of the
S4Vectors
package. This includes lapply
and other data manipulation
and subsetting operations.
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).
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.
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.
[
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.
## 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
#> MSpectra with 2 spectra and 0 metadata column(s):
#> msLevel rtime peaksCount
#> <integer> <numeric> <integer>
#> 1 1 NA 3
#> 2 2 NA 4
spl[[1]]
#> Object of class "Spectrum1"
#> MSn level: 1
#> Total ion count: 3
#> Polarity:
## Add also metadata columns
mcols(spl)$id <- c("a", "b")
mcols(spl)
#> DataFrame with 2 rows and 1 column
#> id
#> <character>
#> 1 a
#> 2 b
## Create a MSpectra with metadata
spl <- MSpectra(sp1, sp2, elementMetadata = DataFrame(id = c("a", "b")))
mcols(spl)
#> DataFrame with 2 rows and 1 column
#> id
#> <character>
#> 1 a
#> 2 b
mcols(spl)$id
#> [1] "a" "b"
## Extract the mz values for the individual spectra
mz(spl)
#> $`1`
#> [1] 1 2 4
#>
#> $`2`
#> [1] 1 2 3 4
#>
## Extract the intensity values for the individual spectra
intensity(spl)
#> $`1`
#> [1] 4 5 2
#>
#> $`2`
#> [1] 5 3 2 5
#>
## Extract the retention time values for the individual spectra
rtime(spl)
#> 1 2
#> NA NA
## Extract the precursor m/z of each spectrum.
precursorMz(spl)
#> 1 2
#> NA 2
## Extract the precursor charge of each spectrum.
precursorCharge(spl)
#> 1 2
#> NA NA
## Extract the precursor scan number for each spectrum.
precScanNum(spl)
#> 1 2
#> NA NA
## Extract the precursor intensity of each spectrum.
precursorIntensity(spl)
#> 1 2
#> NA NA
## Extract the acquisition number of each spectrum.
acquisitionNum(spl)
#> 1 2
#> NA NA
## Extract the scan index of each spectrum.
scanIndex(spl)
#> 1 2
#> NA NA
## Get the number of peaks per spectrum.
peaksCount(spl)
#> 1 2
#> 3 4
## Get the MS level of each spectrum.
msLevel(spl)
#> 1 2
#> 1 2
## Get the total ion current for each spectrum.
tic(spl)
#> 1 2
#> 11 15
## Get the total ion current for each spectrum.
ionCount(spl)
#> 1 2
#> 11 15
## Extract the collision energy for each spectrum.
collisionEnergy(spl)
#> 1 2
#> NA NA
## Extract the file index for each spectrum.
fromFile(spl)
#> 1 2
#> NA NA
## Get the polarity for each spectrum.
polarity(spl)
#> 1 2
#> NA NA
## Whether spectra are smoothed (i.e. processed with the `smooth`
## function).
smoothed(spl)
#> 1 2
#> NA NA
## Are spectra empty (i.e. contain no peak data)?
isEmpty(spl)
#> 1 2
#> FALSE FALSE
## Do the spectra contain centroided data?
centroided(spl)
#> 1 2
#> NA NA
## Do the spectra contain centroided data? Whether spectra are centroided
## is estimated from the peak data.
isCentroided(spl)
#> 1 2
#> NA NA
## 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)
#> [1] "COM=Experimentexported by MSnbase on Thu Mar 14 06:10:11 2024"
#> [2] "BEGIN IONS"
#> [3] "SCANS=NA"
#> [4] "TITLE=msLevel 1; retentionTime ; scanNum NA"
#> [5] "RTINSECONDS="
#> [6] "ID=a"
#> [7] "1 4"
#> [8] "2 5"
#> [9] "4 2"
#> [10] "END IONS"
#> [11] ""
#> [12] "BEGIN IONS"
#> [13] "SCANS="
#> [14] "TITLE=msLevel 2; retentionTime ; scanNum ; precMz 2; precCharge "
#> [15] "RTINSECONDS="
#> [16] "PEPMASS=2"
#> [17] "ID=b"
#> [18] "1 5"
#> [19] "2 3"
#> [20] "3 2"
#> [21] "4 5"
#> [22] "END IONS"
## Set mcols to NULL to avoid export of additional data fields.
mcols(spl) <- NULL
file.remove(tmpf)
#> [1] TRUE
writeMgfData(spl, tmpf)
readLines(tmpf)
#> [1] "COM=Experimentexported by MSnbase on Thu Mar 14 06:10:11 2024"
#> [2] "BEGIN IONS"
#> [3] "SCANS=NA"
#> [4] "TITLE=msLevel 1; retentionTime ; scanNum NA"
#> [5] "RTINSECONDS="
#> [6] "1 4"
#> [7] "2 5"
#> [8] "4 2"
#> [9] "END IONS"
#> [10] ""
#> [11] "BEGIN IONS"
#> [12] "SCANS="
#> [13] "TITLE=msLevel 2; retentionTime ; scanNum ; precMz 2; precCharge "
#> [14] "RTINSECONDS="
#> [15] "PEPMASS=2"
#> [16] "1 5"
#> [17] "2 3"
#> [18] "3 2"
#> [19] "4 5"
#> [20] "END IONS"
## Filter the object by MS level
filterMsLevel(spl, msLevel. = 1)
#> MSpectra with 1 spectra and 0 metadata column(s):
#> msLevel rtime peaksCount
#> <integer> <numeric> <integer>
#> 1 1 NA 3