
Extract spectra associated with features
Source:R/AllGenerics.R
, R/XcmsExperiment.R
, R/methods-XCMSnExp.R
featureSpectra.Rd
This function returns spectra associated with the identified features in
the input object. By default, spectra are returned for all features (from
all MS levels), but parameter features
allows to specify/select features
for which spectra should be returned.
Parameter msLevel
allows to define whether MS level 1 or 2 spectra
should be returned. For msLevel = 1L
MS1 spectra within the
retention time range of each chromatographic peak (in that respective
data file) associated with a feature are returned. For msLevel = 2L
MS2 spectra with a retention time within the retention time range and their
precursor m/z within the m/z range of any chromatographic peak of a feature
are returned. Thus, only MS2 spectra for chromatographic peaks associated
with the feature and also measured in the sample in which the
chromatographic was identified are reported. By default, all spectra
fulfilling the above described condition are reported. This can be adapted
with parameter method
. See the description of method
in the
chromPeakSpectra()
documentation for more information. Internally,
featureSpectra()
uses chromPeakSpectra()
to extract the feature's
chromatographic peaks' spectra, thus any other parameter for this function
can be passed through ...
.
Note that with the default for parameter skipFilled
(skipFilled = FALSE
)
also gap-filled chromatographic peaks are considered. Use
skipFilled = TRUE
to report only spectra for detected peaks.
The information from featureDefinitions
for each feature can be included
in the returned Spectra::Spectra()
object using the featureColumns
parameter.
This is useful for keeping details such as the median retention time
(rtmed
) or median m/z (mzmed
). The columns will retain their names
as specified in the featureDefinitions
data, prefixed by "feature_"
(e.g., "feature_mzmed"
). Additionally, the feature ID (i.e., the row
name of the feature in the featureDefinitions
data frame) is always added
as a metadata column named "feature_id"
.
See also chromPeakSpectra()
, as it supports a similar parameter for
including columns from the chromatographic peaks in the returned spectra
object.
These parameters can be used in combination to include information from both
the chromatographic peaks and the features in the returned
Spectra::Spectra()
.
The peak ID (i.e., the row name of the peak in the chromPeaks
matrix)
is added as a metadata column named "chrom_peak_id"
.
Usage
featureSpectra(object, ...)
# S4 method for class 'XcmsExperiment'
featureSpectra(
object,
msLevel = 2L,
expandRt = 0,
expandMz = 0,
ppm = 0,
skipFilled = FALSE,
return.type = c("Spectra", "List"),
features = character(),
featureColumns = c("rtmed", "mzmed"),
...
)
# S4 method for class 'XCMSnExp'
featureSpectra(
object,
msLevel = 2L,
expandRt = 0,
expandMz = 0,
ppm = 0,
skipFilled = FALSE,
return.type = c("MSpectra", "Spectra", "list", "List"),
features = character(),
...
)
Arguments
- object
XcmsExperiment or XCMSnExp object with feature defitions.
- ...
additional arguments to be passed along to
chromPeakSpectra()
, such asmethod
orchromPeakColumns
.- msLevel
integer(1)
defining the MS level of the spectra that should be returned.- expandRt
numeric(1)
to expand the retention time range of each peak by a constant value on each side.- expandMz
numeric(1)
to expand the m/z range of each peak by a constant value on each side.- ppm
numeric(1)
to expand the m/z range of each peak (on each side) by a value dependent on the peak's m/z.- skipFilled
logical(1)
whether spectra for filled-in peaks should be reported or not. Defaults toskipFilled = FALSE
thus also spectra for gap-filled chromatographic peaks are returned. Set toskipFilled = TRUE
to get only spectra for detected chromatographic peaks.- return.type
character(1)
defining the type of result object that should be returned.- features
character
,logical
orinteger
allowing to specify a subset of features infeatureDefinitions
for which spectra should be returned (providing either their ID, a logical vector same length thannrow(featureDefinitions(x))
or their index infeatureDefinitions(x)
). This parameter is only supported forreturn.type
being either"Spectra"
or"List"
.- featureColumns
character
vector with the names of the columns fromfeatureDefinitions
that should be added to the returned spectra object. The columns will be named as they are written in thefeatureDefinitions
object with the prefix"feature_
. Defaults toc("mzmed", "rtmed")
.
Value
The function returns either a Spectra::Spectra()
(for
return.type = "Spectra"
)
or a List
of Spectra
(for return.type = "List"
). For the latter,
the order and the length matches parameter features
(or if no features
is defined the order of the features in featureDefinitions(object)
).
Spectra variables "chrom_peak_id"
and "feature_id"
define to which
chromatographic peak or feature each individual spectrum is associated
with.