Description Usage Arguments Value Slots Chromatographic peak data Adjusted retention times Correspondence results, features Note Author(s) See Also Examples
The XCMSnExp
object is a container for the results of a G/LC-MS
data preprocessing that comprises chromatographic peak detection, alignment
and correspondence. These results can be accessed with the chromPeaks
,
adjustedRtime
and featureDefinitions
functions; see below
(after the Usage, Arguments, Value and Slots sections) for more details).
Along with the results, the object contains the processing history that
allows to track each processing step along with the used settings. This
can be extracted with the processHistory
method.
XCMSnExp
objects, by directly extending the
OnDiskMSnExp
object from the MSnbase
package, inherit
all of its functionality and allows thus an easy access to the full raw
data at any stage of an analysis.
To support interaction with packages requiring the old objects,
XCMSnExp
objects can be coerced into xcmsSet
objects using the as
method (see examples below). All
preprocessing results will be passed along to the resulting
xcmsSet
object.
General functions for XCMSnExp
objects are (see further below for
specific function to handle chromatographic peak data, alignment and
correspondence results):
processHistoryTypes
returns the available types of
process histories. These can be passed with argument type
to the
processHistory
method to extract specific process step(s).
hasFilledChromPeaks
: whether filled-in peaks are present or not.
profMat
: creates a profile matrix, which
is a n x m matrix, n (rows) representing equally spaced m/z values (bins)
and m (columns) the retention time of the corresponding scans. Each cell
contains the maximum intensity measured for the specific scan and m/z
values. See profMat
for more details and description of
the various binning methods.
hasAdjustedRtime
: whether the object provides adjusted
retention times.
hasFeatures
: whether the object contains correspondence
results (i.e. features).
hasChromPeaks
: whether the object contains peak
detection results.
hasFilledChromPeaks
: whether the object contains any filled-in
chromatographic peaks.
adjustedRtime
,adjustedRtime<-
:
extract/set adjusted retention times. adjustedRtime<-
should not
be called manually, it is called internally by the
adjustRtime
methods. For XCMSnExp
objects,
adjustedRtime<-
does also apply retention time adjustments to
eventually present chromatographic peaks. The bySample
parameter
allows to specify whether the adjusted retention time should be grouped
by sample (file).
featureDefinitions
, featureDefinitions<-
: extract
or set the correspondence results, i.e. the mz-rt features (peak groups).
Similar to the chromPeaks
it is possible to extract features for
specified m/z and/or rt ranges. The function supports also the parameter
type
that allows to specify which features to be returned if any
of rt
or mz
is specified. For details see help of
chromPeaks
.
See also featureSummary
for a function to calculate simple
feature summaries.
chromPeaks
, chromPeaks<-
: extract or set
the matrix containing the information on identified chromatographic
peaks. Rownames of the matrix represent unique IDs of the respective peaks
within the experiment.
Parameter bySample
allows to specify whether peaks should
be returned ungrouped (default bySample = FALSE
) or grouped by
sample (bySample = TRUE
). The chromPeaks<-
method for
XCMSnExp
objects removes also all correspondence (peak grouping)
and retention time correction (alignment) results. The optional
arguments rt
, mz
, ppm
and type
allow to extract
only chromatographic peaks overlapping the defined retention time and/or
m/z ranges. Argument type
allows to define how overlapping is
determined: for type == "any"
(the default), all peaks that are even
partially overlapping the region are returned, for type == "within"
the full peak has to be within the region and for
type == "apex_within"
the peak's apex position (highest signal of the
peak) has to be within the region.
See description of the return value for details on the returned matrix.
Users usually don't have to use the chromPeaks<-
method directly
as detected chromatographic peaks are added to the object by the
findChromPeaks
method. Also, chromPeaks<-
will replace
any existing chromPeakData
.
chromPeakData
and chromPeakData<-
allow to get or set arbitrary
chromatographic peak annotations. These are returned or ar returned as a
DataFrame
. Note that the number of rows and the rownames of the
DataFrame
have to match those of chromPeaks
.
rtime
: extracts the retention time for each
scan. The bySample
parameter allows to return the values grouped
by sample/file and adjusted
whether adjusted or raw retention
times should be returned. By default the method returns adjusted
retention times, if they are available (i.e. if retention times were
adjusted using the adjustRtime
method).
mz
: extracts the mz values from each scan of
all files within an XCMSnExp
object. These values are extracted
from the original data files and eventual processing steps are applied
on the fly. Using the bySample
parameter it is possible to
switch from the default grouping of mz values by spectrum/scan to a
grouping by sample/file.
intensity
: extracts the intensity values from
each scan of all files within an XCMSnExp
object. These values are
extracted from the original data files and eventual processing steps are
applied on the fly. Using the bySample
parameter it is
possible to switch from the default grouping of intensity values by
spectrum/scan to a grouping by sample/file.
spectra
: extracts the
Spectrum
objects containing all data from
object
. The values are extracted from the original data files and
eventual processing steps are applied on the fly. By setting
bySample = TRUE
, the spectra are returned grouped by sample/file.
If the XCMSnExp
object contains adjusted retention times, these
are returned by default in the Spectrum
objects (can be
overwritten by setting adjusted = FALSE
).
processHistory
: returns a list
of
ProcessHistory
objects (or objects inheriting from this
base class) representing the individual processing steps that have been
performed, eventually along with their settings (Param
parameter
class). Optional arguments fileIndex
, type
and
msLevel
allow to restrict to process steps of a certain type or
performed on a certain file or MS level.
dropChromPeaks
: drops any identified chromatographic
peaks and returns the object without that information. Note that for
XCMSnExp
objects the method drops by default also results from a
correspondence (peak grouping) analysis. Adjusted retention times are
removed if the alignment has been performed after peak detection.
This can be overruled with keepAdjustedRtime = TRUE
.
dropFeatureDefinitions
: drops the results from a
correspondence (peak grouping) analysis, i.e. the definition of the mz-rt
features and returns the object without that information. Note that for
XCMSnExp
objects the method will also by default drop retention
time adjustment results, if these were performed after the last peak
grouping (i.e. which base on the results from the peak grouping that are
going to be removed). All related process history steps are
removed too as well as eventually filled in peaks
(by fillChromPeaks
). The parameter keepAdjustedRtime
can be used to avoid removal of adjusted retention times.
dropAdjustedRtime
: drops any retention time
adjustment information and returns the object without adjusted retention
time. For XCMSnExp
objects, this also reverts the retention times
reported for the chromatographic peaks in the peak matrix to the
original, raw, ones (after chromatographic peak detection). Note that
for XCMSnExp
objects the method drops also all peak grouping
results if these were performed after the retention time
adjustment. All related process history steps are removed too.
findChromPeaks
performs chromatographic peak detection
on the provided XCMSnExp
objects. For more details see the method
for XCMSnExp
.
Note that by default (with parameter add = FALSE
) previous peak
detection results are removed. Use add = TRUE
to perform a second
round of peak detection and add the newly identified peaks to the previous
peak detection results. Correspondence results (features) are always removed
prior to peak detection. Previous alignment (retention
time adjustment) results are kept, i.e. chromatographic peak detection
is performed using adjusted retention times if the data was first
aligned using e.g. obiwarp (adjustRtime-obiwarp
).
dropFilledChromPeaks
: drops any filled-in chromatographic
peaks (filled in by the fillChromPeaks
method) and all
related process history steps.
spectrapply
applies the provided function to each
Spectrum
in the object and returns its
results. If no function is specified the function simply returns the
list
of Spectrum
objects.
XCMSnExp
objects can be combined with the c
function. This
combines identified chromatographic peaks and the objects' pheno data but
discards alignment results or feature definitions.
plot
plots the spectrum data (see plot
for
MSnExp
objects in the MSnbase
package for more details.
For type = "XIC"
, identified chromatographic peaks will be indicated
as rectangles with border color peakCol
.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 | processHistoryTypes()
hasFilledChromPeaks(object)
## S4 method for signature 'OnDiskMSnExp'
profMat(
object,
method = "bin",
step = 0.1,
baselevel = NULL,
basespace = NULL,
mzrange. = NULL,
fileIndex,
...
)
## S4 method for signature 'XCMSnExp'
show(object)
## S4 method for signature 'XCMSnExp'
hasAdjustedRtime(object)
## S4 method for signature 'XCMSnExp'
hasFeatures(object, msLevel = integer())
## S4 method for signature 'XCMSnExp'
hasChromPeaks(object, msLevel = integer())
## S4 method for signature 'XCMSnExp'
hasFilledChromPeaks(object)
## S4 method for signature 'XCMSnExp'
adjustedRtime(object, bySample = FALSE)
## S4 replacement method for signature 'XCMSnExp'
adjustedRtime(object) <- value
## S4 method for signature 'XCMSnExp'
featureDefinitions(
object,
mz = numeric(),
rt = numeric(),
ppm = 0,
type = c("any", "within", "apex_within"),
msLevel = integer()
)
## S4 replacement method for signature 'XCMSnExp'
featureDefinitions(object) <- value
## S4 method for signature 'XCMSnExp'
chromPeaks(
object,
bySample = FALSE,
rt = numeric(),
mz = numeric(),
ppm = 0,
msLevel = integer(),
type = c("any", "within", "apex_within"),
isFilledColumn = FALSE
)
## S4 replacement method for signature 'XCMSnExp'
chromPeaks(object) <- value
## S4 method for signature 'XCMSnExp'
rtime(object, bySample = FALSE, adjusted = hasAdjustedRtime(object))
## S4 method for signature 'XCMSnExp'
mz(object, bySample = FALSE, BPPARAM = bpparam())
## S4 method for signature 'XCMSnExp'
intensity(object, bySample = FALSE, BPPARAM = bpparam())
## S4 method for signature 'XCMSnExp'
spectra(
object,
bySample = FALSE,
adjusted = hasAdjustedRtime(object),
BPPARAM = bpparam()
)
## S4 method for signature 'XCMSnExp'
processHistory(object, fileIndex, type, msLevel)
## S4 method for signature 'XCMSnExp'
dropChromPeaks(object, keepAdjustedRtime = FALSE)
## S4 method for signature 'XCMSnExp'
dropFeatureDefinitions(object, keepAdjustedRtime = FALSE, dropLastN = -1)
## S4 method for signature 'XCMSnExp'
dropAdjustedRtime(object)
## S4 method for signature 'XCMSnExp'
profMat(
object,
method = "bin",
step = 0.1,
baselevel = NULL,
basespace = NULL,
mzrange. = NULL,
fileIndex,
...
)
## S4 method for signature 'XCMSnExp,Param'
findChromPeaks(
object,
param,
BPPARAM = bpparam(),
return.type = "XCMSnExp",
msLevel = 1L,
add = FALSE
)
## S4 method for signature 'XCMSnExp'
dropFilledChromPeaks(object)
## S4 method for signature 'XCMSnExp'
spectrapply(object, FUN = NULL, BPPARAM = bpparam(), ...)
## S3 method for class 'XCMSnExp'
c(...)
## S4 method for signature 'XCMSnExp'
chromPeakData(object)
## S4 replacement method for signature 'XCMSnExp'
chromPeakData(object) <- value
## S4 method for signature 'XCMSnExp,missing'
plot(x, y, type = c("spectra", "XIC"), peakCol = "#ff000060", ...)
|
object |
For |
method |
The profile matrix generation method. Allowed are |
step |
numeric(1) representing the m/z bin size. |
baselevel |
numeric(1) representing the base value to which
empty elements (i.e. m/z bins without a measured intensity) should be
set. Only considered if |
basespace |
numeric(1) representing the m/z length after
which the signal will drop to the base level. Linear interpolation will
be used between consecutive data points falling within
|
mzrange. |
Optional numeric(2) manually specifying the mz value range to be used for binnind. If not provided, the whole mz value range is used. |
fileIndex |
For |
... |
Additional parameters. |
msLevel |
|
bySample |
logical(1) specifying whether results should be grouped by sample. |
value |
For For For |
mz |
optional |
rt |
optional |
ppm |
optional |
type |
For |
isFilledColumn |
|
adjusted |
logical(1) whether adjusted or raw (i.e. the original retention times reported in the files) should be returned. |
BPPARAM |
Parameter class for parallel processing. See
|
keepAdjustedRtime |
For |
dropLastN |
For |
param |
A |
return.type |
Character specifying what type of object the method should
return. Can be either |
add |
For |
FUN |
For |
x |
For |
y |
For |
peakCol |
For |
For profMat
: a list
with a the profile matrix
matrix
(or matrices if fileIndex
was not specified or if
length(fileIndex) > 1
). See profile-matrix
for
general help and information about the profile matrix.
For adjustedRtime
: if bySample = FALSE
a numeric
vector with the adjusted retention for each spectrum of all files/samples
within the object. If bySample = TRUE
a list
(length equal
to the number of samples) with adjusted retention times grouped by
sample. Returns NULL
if no adjusted retention times are present.
For featureDefinitions
: a DataFrame
with peak grouping
information, each row corresponding to one mz-rt feature (grouped peaks
within and across samples) and columns "mzmed"
(median mz value),
"mzmin"
(minimal mz value), "mzmax"
(maximum mz value),
"rtmed"
(median retention time), "rtmin"
(minimal retention
time), "rtmax"
(maximal retention time) and "peakidx"
.
Column "peakidx"
contains a list
with indices of
chromatographic peaks (rows) in the matrix returned by the
chromPeaks
method that belong to that feature group. The method
returns NULL
if no feature definitions are present.
For chromPeaks
: if bySample = FALSE
a matrix
(each row
being a chromatographic peak, rownames representing unique IDs of the peaks)
with at least the following columns:
"mz"
(intensity-weighted mean of mz values of the peak across
scans/retention times),
"mzmin"
(minimal mz value),
"mzmax"
(maximal mz value),
"rt"
(retention time of the peak apex),
"rtmin"
(minimal retention time),
"rtmax"
(maximal retention time),
"into"
(integrated, original, intensity of the peak),
"maxo"
(maximum intentity of the peak),
"sample"
(sample index in which the peak was identified) and
Depending on the employed peak detection algorithm and the
verboseColumns
parameter of it, additional columns might be
returned. If parameter isFilledColumn
was set to TRUE
a column
named "is_filled"
is also returned.
For bySample = TRUE
the chromatographic peaks are
returned as a list
of matrices, each containing the
chromatographic peaks of a specific sample. For samples in which no
peaks were detected a matrix with 0 rows is returned.
For rtime
: if bySample = FALSE
a numeric vector with
the retention times of each scan, if bySample = TRUE
a
list
of numeric vectors with the retention times per sample.
For mz
: if bySample = FALSE
a list
with the mz
values (numeric vectors) of each scan. If bySample = TRUE
a
list
with the mz values per sample.
For intensity
: if bySample = FALSE
a list
with
the intensity values (numeric vectors) of each scan. If
bySample = TRUE
a list
with the intensity values per
sample.
For spectra
: if bySample = FALSE
a list
with
Spectrum
objects. If bySample = TRUE
the
result is grouped by sample, i.e. as a list
of lists
, each
element in the outer list
being the list
of spectra
of the specific file.
For processHistory
: a list
of
ProcessHistory
objects providing the details of the
individual data processing steps that have been performed.
.processHistory
list
with XProcessHistory
objects
tracking all individual analysis steps that have been performed.
msFeatureData
MsFeatureData
class extending environment
and containing the results from a chromatographic peak detection (element
"chromPeaks"
), peak grouping (element "featureDefinitions"
)
and retention time correction (element "adjustedRtime"
) steps.
This object should not be manipulated directly.
Chromatographic peak data is added to an XCMSnExp
object by the
findChromPeaks
function. Functions to access chromatographic
peak data are:
hasChromPeaks
whether chromatographic peak data is available,
see below for help of the function.
chromPeaks
access chromatographic peaks (see below for help).
dropChromPeaks
remove chromatographic peaks (see below for
help).
dropFilledChromPeaks
remove filled-in peaks (see below for
help).
fillChromPeaks
fill-in missing peaks (see respective
help page).
plotChromPeaks
plot identified peaks for a file (see
respective help page).
plotChromPeakImage
plot distribution of peaks along the
retention time axis (see respective help page).
highlightChromPeaks
add chromatographic peaks to an
existing plot of a Chromatogram
(see respective help page).
Adjusted retention times are stored in an XCMSnExp
object besides the
original, raw, retention times, allowing to switch between raw and adjusted
times. It is also possible to replace the raw retention times with the
adjusted ones with the applyAdjustedRtime
. The adjusted
retention times are added to an XCMSnExp
by the
adjustRtime
function. All functions related to the access of
adjusted retention times are:
hasAdjustedRtime
whether adjusted retention times are available
(see below for help).
dropAdjustedRtime
remove adjusted retention times (see below
for help).
applyAdjustedRtime
replace the raw retention times with
the adjusted ones (see respective help page).
plotAdjustedRtime
plot differences between adjusted and
raw retention times (see respective help page).
The correspondence analysis (groupChromPeaks
) adds the feature
definitions to an XCMSnExp
object. All functions related to these are
listed below:
hasFeatures
whether correspondence results are available (see
below for help).
featureDefinitions
access the definitions of the features (see
below for help).
dropFeatureDefinitions
remove correspondence results (see below
for help).
featureValues
access values for features (see respective
help page).
featureSummary
perform a simple summary of the defined
features (see respective help page).
overlappingFeatures
identify features that are
overlapping or close in the m/z - rt space (see respective help page).
quantify
extract feature intensities and put them, along
with feature definitions and phenodata information, into a
SummarizedExperiment
. See help page for details.
The "chromPeaks"
element in the msFeatureData
slot is
equivalent to the @peaks
slot of the xcmsSet
object, the
"featureDefinitions"
contains information from the @groups
and @groupidx
slots from an xcmsSet
object.
Johannes Rainer
xcmsSet
for the old implementation.
OnDiskMSnExp
, MSnExp
and pSet
for a complete list of inherited methods.
findChromPeaks
for available peak detection methods
returning a XCMSnExp
object as a result.
groupChromPeaks
for available peak grouping
methods and featureDefinitions
for the method to extract
the feature definitions representing the peak grouping results.
adjustRtime
for retention time adjustment methods.
chromatogram
to extract MS data as
Chromatogram
objects.
as
(as(x, "data.frame")
) in the MSnbase
package for the method to extract MS data as data.frame
s.
featureSummary
to calculate basic feature summaries.
featureChromatograms
to extract chromatograms for each
feature.
chromPeakSpectra
to extract MS2 spectra with the m/z of
the precursor ion within the m/z range of a peak and a retention time
within its retention time range.
featureSpectra
to extract MS2 spectra associated with
identified features.
fillChromPeaks
for the method to fill-in eventually
missing chromatographic peaks for a feature in some samples.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 | ## Load a test data set with detected peaks
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")
## Disable parallel processing for this example
register(SerialParam())
## The results from the peak detection are now stored in the XCMSnExp
## object
faahko_sub
## The detected peaks can be accessed with the chromPeaks method.
head(chromPeaks(faahko_sub))
## The settings of the chromatographic peak detection can be accessed with
## the processHistory method
processHistory(faahko_sub)
## Also the parameter class for the peak detection can be accessed
processParam(processHistory(faahko_sub)[[1]])
## The XCMSnExp inherits all methods from the pSet and OnDiskMSnExp classes
## defined in Bioconductor's MSnbase package. To access the (raw) retention
## time for each spectrum we can use the rtime method. Setting bySample = TRUE
## would cause the retention times to be grouped by sample
head(rtime(faahko_sub))
## Similarly it is possible to extract the mz values or the intensity values
## using the mz and intensity method, respectively, also with the option to
## return the results grouped by sample instead of the default, which is
## grouped by spectrum. Finally, to extract all of the data we can use the
## spectra method which returns Spectrum objects containing all raw data.
## Note that all these methods read the information from the original input
## files and subsequently apply eventual data processing steps to them.
mzs <- mz(faahko_sub, bySample = TRUE)
length(mzs)
lengths(mzs)
## The full data could also be read using the spectra data, which returns
## a list of Spectrum object containing the mz, intensity and rt values.
## spctr <- spectra(faahko_sub)
## To get all spectra of the first file we can split them by file
## head(split(spctr, fromFile(faahko_sub))[[1]])
############
## Filtering
##
## XCMSnExp objects can be filtered by file, retention time, mz values or
## MS level. For some of these filter preprocessing results (mostly
## retention time correction and peak grouping results) will be dropped.
## Below we filter the XCMSnExp object by file to extract the results for
## only the second file.
xod_2 <- filterFile(faahko_sub, file = 2)
xod_2
## Now the objects contains only the idenfified peaks for the second file
head(chromPeaks(xod_2))
##########
## Coercing to an xcmsSet object
##
## We can also coerce the XCMSnExp object into an xcmsSet object:
xs <- as(faahko_sub, "xcmsSet")
head(peaks(xs))
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.