Description Usage Arguments Value Creation of objects Filtering and subsetting Accessing data Plotting and visualizing Chromatographic peak detection Correspondence analysis Note Author(s) See Also Examples
View source: R/functions-XChromatogram.R
The XChromatogram
object allows to store chromatographic data (e.g.
an extracted ion chromatogram) along with identified chromatographic peaks
within that data. The object inherits all functions from the Chromatogram()
object in the MSnbase
package.
Multiple XChromatogram
objects can be stored in a XChromatograms
object.
This class extends MChromatograms()
from the MSnbase
package and allows
thus to arrange chromatograms in a matrix-like structure, columns
representing samples and rows m/z-retention time ranges.
All functions are described (grouped into topic-related sections) after the Arguments section.
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 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 | XChromatograms(data, phenoData, featureData, chromPeaks, chromPeakData, ...)
XChromatogram(
rtime = numeric(),
intensity = numeric(),
mz = c(NA_real_, NA_real_),
filterMz = c(NA_real_, NA_real_),
precursorMz = c(NA_real_, NA_real_),
productMz = c(NA_real_, NA_real_),
fromFile = integer(),
aggregationFun = character(),
msLevel = 1L,
chromPeaks,
chromPeakData
)
## S4 method for signature 'XChromatogram'
show(object)
## S4 method for signature 'XChromatogram'
chromPeaks(
object,
rt = numeric(),
mz = numeric(),
ppm = 0,
type = c("any", "within", "apex_within"),
msLevel
)
## S4 replacement method for signature 'XChromatogram'
chromPeaks(object) <- value
## S4 method for signature 'XChromatogram,ANY'
plot(
x,
col = "#00000060",
lty = 1,
type = "l",
xlab = "retention time",
ylab = "intensity",
main = NULL,
peakType = c("polygon", "point", "rectangle", "none"),
peakCol = "#00000060",
peakBg = "#00000020",
peakPch = 1,
...
)
## S4 method for signature 'XChromatogram'
filterMz(object, mz, ...)
## S4 method for signature 'XChromatogram'
filterRt(object, rt, ...)
## S4 method for signature 'XChromatogram'
hasChromPeaks(object)
## S4 method for signature 'XChromatogram'
dropFilledChromPeaks(object)
## S4 method for signature 'XChromatogram'
chromPeakData(object)
## S4 replacement method for signature 'XChromatogram'
chromPeakData(object) <- value
## S4 method for signature 'XChromatogram,MergeNeighboringPeaksParam'
refineChromPeaks(object, param = MergeNeighboringPeaksParam())
## S4 method for signature 'XChromatograms'
show(object)
## S4 method for signature 'XChromatograms'
hasChromPeaks(object)
## S4 method for signature 'XChromatograms'
hasFilledChromPeaks(object)
## S4 method for signature 'XChromatograms'
chromPeaks(
object,
rt = numeric(),
mz = numeric(),
ppm = 0,
type = c("any", "within", "apex_within"),
msLevel
)
## S4 method for signature 'XChromatograms'
chromPeakData(object)
## S4 method for signature 'XChromatograms'
filterMz(object, mz, ...)
## S4 method for signature 'XChromatograms'
filterRt(object, rt, ...)
## S4 method for signature 'XChromatograms,ANY'
plot(
x,
col = "#00000060",
lty = 1,
type = "l",
xlab = "retention time",
ylab = "intensity",
main = NULL,
peakType = c("polygon", "point", "rectangle", "none"),
peakCol = "#00000060",
peakBg = "#00000020",
peakPch = 1,
...
)
## S4 method for signature 'XChromatograms'
processHistory(object, fileIndex, type)
## S4 method for signature 'XChromatograms'
hasFeatures(object, ...)
## S4 method for signature 'XChromatograms'
dropFeatureDefinitions(object, ...)
## S4 method for signature 'XChromatograms,PeakDensityParam'
groupChromPeaks(object, param)
## S4 method for signature 'XChromatograms'
featureDefinitions(
object,
mz = numeric(),
rt = numeric(),
ppm = 0,
type = c("any", "within", "apex_within")
)
## S4 method for signature 'XChromatograms,ANY,ANY,ANY'
x[i, j, drop = FALSE]
## S4 method for signature 'XChromatograms'
featureValues(
object,
method = c("medret", "maxint", "sum"),
value = "into",
intensity = "into",
missing = NA,
...
)
## S4 method for signature 'XChromatograms'
plotChromPeakDensity(
object,
param,
col = "#00000060",
xlab = "retention time",
main = NULL,
peakType = c("polygon", "point", "rectangle", "none"),
peakCol = "#00000060",
peakBg = "#00000020",
peakPch = 1,
simulate = TRUE,
...
)
## S4 method for signature 'XChromatograms'
dropFilledChromPeaks(object)
## S4 method for signature 'XChromatograms,MergeNeighboringPeaksParam'
refineChromPeaks(object, param = MergeNeighboringPeaksParam())
|
data |
For |
phenoData |
For |
featureData |
For |
chromPeaks |
For |
chromPeakData |
For |
... |
For |
rtime |
For |
intensity |
For For `featureValues`: `character(1)` specifying the name of the column in `chromPeaks(object)` containing the intensity value of the peak that should be used for the `method = "maxint"` conflict resolution if. |
mz |
For |
filterMz |
For |
precursorMz |
For |
productMz |
For |
fromFile |
For |
aggregationFun |
For |
msLevel |
For |
object |
An |
rt |
For |
ppm |
For |
type |
For For `plot`: what type of plot should be used for the chromatogram (such as `"l"` for lines, `"p"` for points etc), see help of [plot()] in the `graphics` package for more details. For `processHistory`: restrict returned processing steps to specific types. Use [processHistoryTypes()] to list all supported values. |
value |
For For `featureValues`: `character(1)` specifying the name of the column in `chromPeaks(object)` that should be returned or `"index"` (default) to return the index of the peak associated with the feature in each sample. To return the integrated peak area instead of the index use `value = "into"`. |
x |
For |
col |
For |
lty |
For |
xlab |
For |
ylab |
For |
main |
For |
peakType |
For |
peakCol |
For |
peakBg |
For |
peakPch |
For |
param |
For |
fileIndex |
For |
i |
For |
j |
For |
drop |
For |
method |
For |
missing |
For |
simulate |
For |
See help of the individual functions.
Objects can be created with the contructor function XChromatogram
and
XChromatograms
, respectively. Also, they can be coerced from
Chromatogram or MChromatograms()
objects using
as(object, "XChromatogram")
or as(object, "XChromatograms")
.
Besides classical subsetting with [
specific filter operations on
MChromatograms()
and XChromatograms
objects are available. See
filterColumnsIntensityAbove()
for more details.
[
allows to subset a XChromatograms
object by row (i
) and column
(j
), with i
and j
being of type integer
. The featureDefinitions
will also be subsetted accordingly and the peakidx
column updated.
filterMz
filters the chromatographic peaks within an XChromatogram
or
XChromatograms
, if a column "mz"
is present in the chromPeaks
matrix.
This would be the case if the XChromatogram
was extracted from an
XCMSnExp()
object with the chromatogram()
function. All
chromatographic peaks with their m/z within the m/z range defined by mz
will be retained. Also feature definitions (if present) will be subset
accordingly. The function returns a filtered XChromatogram
or
XChromatograms
object.
filterRt
filters chromatogram(s) by the provided retention time range.
All eventually present chromatographic peaks with their apex within the
retention time range specified with rt
will be retained. Also feature
definitions, if present, will be filtered accordingly. The function
returns a filtered XChromatogram
or XChromatograms
object.
See also help of Chromatogram in the MSnbase
package for general
information and data access. The methods listed here are specific for
XChromatogram
and XChromatograms
objects.
chromPeaks
, chromPeaks<-
: extract or set the matrix with the
chromatographic peak definitions. Parameter rt
allows to specify a
retention time range for which peaks should be returned along with
parameter type
that defines how overlapping is defined (parameter
description for details). For XChromatogram
objects the function returns
a matrix
with columns "rt"
(retention time of the peak apex),
"rtmin"
(the lower peak boundary), "rtmax"
(the upper peak boundary),
"into"
(the ingegrated peak signal/area of the peak), "maxo"
(the
maximum instensity of the peak and "sn"
(the signal to noise ratio).
Note that, depending on the peak detection algorithm, the matrix may
contain additional columns.
For XChromatograms
objects the matrix
contains also columns "row"
and "column"
specifying in which chromatogram of object
the peak was
identified. Chromatographic peaks are ordered by row.
chromPeakData
, chromPeakData<-
: extract or set the DataFrame()
with
optional chromatographic peak annotations.
hasChromPeaks
: infer whether a XChromatogram
(or XChromatograms
)
has chromatographic peaks. For XChromatogram
: returns a logical(1)
,
for XChromatograms
: returns a matrix
, same dimensions than object
with either TRUE
or FALSE
if chromatographic peaks are available in
the chromatogram at the respective position.
hasFilledChromPeaks
: whether a XChromatogram
(or a XChromatogram
in
a XChromatograms
) has filled-in chromatographic peaks.
For XChromatogram
: returns a logical(1)
,
for XChromatograms
: returns a matrix
, same dimensions than object
with either TRUE
or FALSE
if chromatographic peaks are available in
the chromatogram at the respective position.
dropFilledChromPeaks
: removes filled-in chromatographic peaks. See
dropFilledChromPeaks()
help for XCMSnExp()
objects for more
information.
hasFeatures
: for XChromatograms
objects only: if correspondence
analysis has been performed and m/z-rt feature definitions are present.
Returns a logical(1)
.
dropFeatureDefinitions
: for XChrmomatograms
objects only: delete any
correspondence analysis results (and related process history).
featureDefinitions
: for XChromatograms
objects only. Extract the
results from the correspondence analysis (performed with
groupChromPeaks
). Returns a DataFrame
with the properties of the
defined m/z-rt features: their m/z and retention time range. Columns
peakidx
and row
contain the index of the chromatographic peaks in the
chromPeaks
matrix associated with the feature and the row in the
XChromatograms
object in which the feature was defined. Similar to the
chromPeaks
method it is possible to filter the returned feature matrix
with the mz
, rt
and ppm
parameters.
featureValues
: for XChromatograms
objects only. Extract the abundance
estimates for the individuals features. Note that by default (with
parameter value = "index"
a matrix
of indices of the peaks in the
chromPeaks
matrix associated to the feature is returned. To extract the
integrated peak area use value = "into"
. The function returns a matrix
with one row per feature (in featureDefinitions
) and each column being
a sample (i.e. column of object
). For features without a peak associated
in a certain sample NA
is returned. This can be changed with the
missing
argument of the function.
processHistory
: returns a list
of ProcessHistory objects representing
the individual performed processing steps. Optional parameters type
and
fileIndex
allow to further specify which processing steps to return.
plot
draws the chromatogram and highlights in addition any
chromatographic peaks present in the XChromatogram
or XChromatograms
(unless peakType = "none"
was specified). To draw peaks in different
colors a vector of color definitions with length equal to
nrow(chromPeaks(x))
has to be submitted with peakCol
and/or peakBg
defining one color for each peak (in the order as peaks are in
chromPeaks(x))
. For base peak chromatograms or total ion chromatograms
it might be better to set peakType = "none"
to avoid generating busy
plots.
plotChromPeakDensity
: visualize peak density-based correspondence
analysis results. See section Correspondence analysis for more details.
See findChromPeaks-Chromatogram-CentWaveParam for information.
After chromatographic peak detection it is also possible to refine
identified chromatographic peaks with the refineChromPeaks
method (e.g. to
reduce peak detection artifacts). Currently, only peak refinement using the
merge neighboring peaks method is available (see
MergeNeighboringPeaksParam()
for a detailed description of the approach.
Identified chromatographic peaks in an XChromatograms
object can be grouped
into features with the groupChromPeaks
function. Currently, such a
correspondence analysis can be performed with the peak density method
(see groupChromPeaks for more details) specifying the algorithm settings
with a PeakDensityParam()
object. A correspondence analysis is performed
separately for each row in the XChromatograms
object grouping
chromatographic peaks across samples (columns).
The analysis results are stored in the returned XChromatograms
object
and can be accessed with the featureDefinitions
method which returns a
DataFrame
with one row for each feature. Column "row"
specifies in
which row of the XChromatograms
object the feature was identified.
The plotChromPeakDensity
method can be used to visualize peak density
correspondence results, or to simulate a peak density correspondence
analysis on chromatographic data. The resulting plot consists of two panels,
the upper panel showing the chromatographic data as well as the identified
chromatographic peaks, the lower panel the distribution of peaks (the peak
density) along the retention time axis. This plot shows each peak as a point
with it's peak's retention time on the x-axis, and the sample in which it
was found on the y-axis. The distribution of peaks along the retention time
axis is visualized with a density estimate. Grouped chromatographic peaks
are indicated with grey shaded rectangles. Parameter simulate
allows to
define whether the correspondence analysis should be simulated (
simulate=TRUE
, based on the available data and the provided
PeakDensityParam()
parameter class) or not (simulate=FALSE
). For the
latter it is assumed that a correspondence analysis has been performed with
the peak density method on the object
.
See examples below.
Abundance estimates for each feature can be extracted with the
featureValues
function using parameter value = "into"
to extract the
integrated peak area for each feature. The result is a matrix
, columns
being samples and rows features.
Highlighting the peak area(s) in an XChromatogram
or XChromatograms
object (plot
with peakType = "polygon"
) draws a polygon representing
the displayed chromatogram from the peak's minimal retention time to the
maximal retention time. If the XChromatograms
was extracted from an
XCMSnExp()
object with the chromatogram()
function this might not
represent the actual identified peak area if the m/z range that was
used to extract the chromatogram was larger than the peak's m/z.
Johannes Rainer
findChromPeaks-centWave for peak
detection on MChromatograms()
objects.
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 134 135 136 137 138 139 140 141 142 | ## ---- Creation of XChromatograms ----
##
## Create a XChromatograms from Chromatogram objects
dta <- list(Chromatogram(rtime = 1:7, c(3, 4, 6, 12, 8, 3, 2)),
Chromatogram(1:10, c(4, 6, 3, 4, 7, 13, 43, 34, 23, 9)))
## Create an XChromatograms without peak data
xchrs <- XChromatograms(dta)
## Create an XChromatograms with peaks data
pks <- list(matrix(c(4, 2, 5, 30, 12, NA), nrow = 1,
dimnames = list(NULL, c("rt", "rtmin", "rtmax", "into", "maxo", "sn"))),
NULL)
xchrs <- XChromatograms(dta, chromPeaks = pks)
## Create an XChromatograms from XChromatogram objects
dta <- lapply(dta, as, "XChromatogram")
chromPeaks(dta[[1]]) <- pks[[1]]
xchrs <- XChromatograms(dta, nrow = 1)
hasChromPeaks(xchrs)
## Loading a test data set with identified chromatographic peaks
data(faahko_sub)
## Update the path to the files for the local system
dirname(faahko_sub) <- system.file("cdf/KO", package = "faahKO")
## Subset the dataset to the first and third file.
xod_sub <- filterFile(faahko_sub, file = c(1, 3))
od <- as(xod_sub, "OnDiskMSnExp")
## Extract chromatograms for a m/z - retention time slice
chrs <- chromatogram(od, mz = 344, rt = c(2500, 3500))
chrs
## --------------------------------------------------- ##
## Chromatographic peak detection ##
## --------------------------------------------------- ##
## Perform peak detection using CentWave
xchrs <- findChromPeaks(chrs, param = CentWaveParam())
xchrs
## Do we have chromatographic peaks?
hasChromPeaks(xchrs)
## Process history
processHistory(xchrs)
## The chromatographic peaks, columns "row" and "column" provide information
## in which sample the peak was identified.
chromPeaks(xchrs)
## Spectifically extract chromatographic peaks for one sample/chromatogram
chromPeaks(xchrs[1, 2])
## Plot the results
plot(xchrs)
## Plot the results using a different color for each sample
sample_colors <- c("#ff000040", "#00ff0040", "#0000ff40")
cols <- sample_colors[chromPeaks(xchrs)[, "column"]]
plot(xchrs, col = sample_colors, peakBg = cols)
## Indicate the peaks with a rectangle
plot(xchrs, col = sample_colors, peakCol = cols, peakType = "rectangle",
peakBg = NA)
## --------------------------------------------------- ##
## Correspondence analysis ##
## --------------------------------------------------- ##
## Group chromatographic peaks across samples
prm <- PeakDensityParam(sampleGroup = rep(1, 2))
res <- groupChromPeaks(xchrs, param = prm)
hasFeatures(res)
featureDefinitions(res)
## Plot the correspondence results. Use simulate = FALSE to show the
## actual results. Grouped chromatographic peaks are indicated with
## grey shaded rectangles.
plotChromPeakDensity(res, simulate = FALSE)
## Simulate a correspondence analysis based on different settings. Larger
## bw will increase the smoothing of the density estimate hence grouping
## chromatographic peaks that are more apart on the retention time axis.
prm <- PeakDensityParam(sampleGroup = rep(1, 3), bw = 60)
plotChromPeakDensity(res, param = prm)
## Delete the identified feature definitions
res <- dropFeatureDefinitions(res)
hasFeatures(res)
## Create a XChromatogram object
pks <- matrix(nrow = 1, ncol = 6)
colnames(pks) <- c("rt", "rtmin", "rtmax", "into", "maxo", "sn")
pks[, "rtmin"] <- 2
pks[, "rtmax"] <- 9
pks[, "rt"] <- 4
pks[, "maxo"] <- 19
pks[, "into"] <- 93
xchr <- XChromatogram(rtime = 1:10,
intensity = c(4, 8, 14, 19, 18, 12, 9, 8, 5, 2),
chromPeaks = pks)
xchr
## Add arbitrary peak annotations
df <- DataFrame(peak_id = c("a"))
xchr <- XChromatogram(rtime = 1:10,
intensity = c(4, 8, 14, 19, 18, 12, 9, 8, 5, 2),
chromPeaks = pks, chromPeakData = df)
xchr
chromPeakData(xchr)
## Extract the chromatographic peaks
chromPeaks(xchr)
## Plotting of a single XChromatogram object
## o Don't highlight chromatographic peaks
plot(xchr, peakType = "none")
## o Indicate peaks with a polygon
plot(xchr)
## Add a second peak to the data.
pks <- rbind(chromPeaks(xchr), c(7, 7, 10, NA, 15, NA))
chromPeaks(xchr) <- pks
## Plot the peaks in different colors
plot(xchr, peakCol = c("#ff000080", "#0000ff80"),
peakBg = c("#ff000020", "#0000ff20"))
## Indicate the peaks as rectangles
plot(xchr, peakCol = c("#ff000060", "#0000ff60"), peakBg = NA,
peakType = "rectangle")
## Filter the XChromatogram by retention time
xchr_sub <- filterRt(xchr, rt = c(4, 6))
xchr_sub
plot(xchr_sub)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.