yclement/xcms
LC-MS and GC-MS Data Analysis

Package index
Search the yclement/xcms package
Vignettes
Functions
1242
Source code
94
Man pages
171
Home
/
GitHub
/
yclement/xcms
/
XChromatogram: Containers for chromatographic and peak detection data

XChromatogram: Containers for chromatographic and peak detection data
In yclement/xcms: LC-MS and GC-MS Data Analysis

Description Usage Arguments Value Creation of objects Accessing data Plotting and visualizing Filtering and subsetting Chromatographic peak detection Correspondence analysis Note Author(s) See Also Examples

View source: R/functions-XChromatogram.R

Description

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 Chromatograms() 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.

Usage

  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())

Arguments

data

For XChromatograms: list of Chromatogram or XChromatogram objects.

phenoData

For XChromatograms: either a data.frame, AnnotatedDataFrame or NAnnotatedDataFrame describing the phenotypical information of the samples.

featureData

For XChromatograms: either a data.frame or AnnotatedDataFrame with additional information for each row of chromatograms.

chromPeaks

For XChromatogram: matrix with required columns "rt", "rtmin", "rtmax", "into", "maxo" and "sn". For XChromatograms: list, same length than data, with the chromatographic peaks for each chromatogram. Each element has to be a matrix, the ordering has to match the order of the chromatograms in data.

chromPeakData

For XChromatogram: DataFrame with optional additional annotations for each chromatographic peak. The number of rows has to match the number of chromatographic peaks.

...

For plot: additional parameters to passed to the plot function. For XChromatograms: additional parameters to be passed to the matrix constructor, such as nrow, ncol and byrow.

rtime

For XChromatogram: numeric with the retention times (length has to be equal to the length of intensity).

intensity

For XChromatogram: numeric with the intensity values (length has to be equal to the length of rtime).

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 XChromatogram: numeric(2) representing the m/z value range (min, max) on which the chromatogram was created. This is supposed to contain the real range of m/z values in contrast to the filterMz below. For chromPeaks and featureDefinitions: numeric(2) defining the m/z range for which chromatographic peaks or features should be returned. For filterMz: numeric(2) defining the m/z range for which chromatographic peaks should be retained.#'

filterMz

For XChromatogram: numeric(2) representing the m/z value range (min, max) that was used to filter the original object on m/z dimension. If not applicable use filterMz = c(0, 0).

precursorMz

For XChromatogram: numeric(2) for SRM/MRM transitions. Represents the mz of the precursor ion. See details for more information.

productMz

For XChromatogram: numeric(2) for SRM/MRM transitions. Represents the mz of the product. See details for more information.

fromFile

For XChromatogram: integer(1) the index of the file within the OnDiskMSnExp or MSnExp object from which the chromatogram was extracted.

aggregationFun

For XChromatogram: character(1) specifying the function that was used to aggregate intensity values for the same retention time across the m/z range.

msLevel

For XChromatogram: integer with the MS level from which the chromatogram was extracted. For chromPeaks and chromPeakData: extract chromatographic peaks of a certain MS level.

object

An XChromatogram or XChromatograms object.

rt

For chromPeaks and featureDefinitions: numeric(2) defining the retention time range for which chromatographic peaks or features should be returned. For filterRt: numeric(2) defining the retention time range to reduce object to.

ppm

For chromPeaks and featureDefinitions: numeric(1) defining a ppm to expand the provided m/z range.

type

For chromPeaks and featureDefinitions: character(1) defining which peaks or features to return if rt or mz is provided: "any" (default) return all peaks that are even partially overlapping with rt, "within" return peaks that are completely within rt and "apex_within" return peaks which apex is within rt.

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 chromPeaks<-: a numeric matrix with required columns "rt", "rtmin", "rtmax", "into" and "maxo".

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 plot: an XChromatogram or XChromatograms object.

col

For plot: the color to be used to draw the chromatogram.

lty

For plot and plotChromPeakDensity: the line type.

xlab

For plot and plotChromPeakDensity: the x axis label.

ylab

For plot: the y axis label.

main

For plot and plotChromPeakDensity: an optional title for the plot.

peakType

For plot and plotChromPeakDensity: character(1) defining how (and if) identified chromatographic peak within the chromatogram should be plotted. Options are "polygon" (default): draw the peak borders with the peakCol color and fill the peak area with the peakBg color, "point": indicate the peak's apex with a point, "rectangle": draw a rectangle around the identified peak and "none": don't draw peaks.

peakCol

For plot and plotChromPeakDensity: the foreground color for the peaks. For peakType = "polygon" and peakType = "rectangle" this is the color for the border. Use NA to not use a foreground color. This should either be a single color or a vector of colors with the same length than chromPeaks(x) has rows.

peakBg

For plot and plotChromPeakDensity: the background color for the peaks. For peakType = "polygon" and peakType = "rectangle" the peak are or rectangle will be filled with this color. Use NA to skip. This should be either a single color or a vector of colors with the same length than chromPeaks(x) has rows.

peakPch

For plot and plotChromPeakDensity: the point character to be used for peakType = "point". See plot() in the graphics package for more details.

param

For groupChromPeaks and plotChromPeakDensity: a PeakDensityParam() object with the settings for the peak density correspondence analysis algorithm.

fileIndex

For processHistory: optional integer specifying the index of the files/samples for which the ProcessHistory objects should be returned.

i

For [: integer with the row indices to subset the XChromatograms object.

j

For [: integer with the column indices to subset the XChromatograms object.

drop

For [: logical(1) whether the dimensionality should be dropped (if possible).

method

For featureValues: character(1) specifying the method to resolve multi-peak mappings within the sample sample, i.e. to select the representative peak for a feature for which more than one peak was assigned in one sample. Options are "medret" (default): select the peak closest to the median retention time of the feature, "maxint": select the peak with the largest signal and "sum": sum the values of all peaks (only if value is "into" or "maxo").

missing

For featureValues: how missing values should be reported. Allowed values are NA (default), a numeric(1) to replace NAs with that value or missing = "rowmin_half" to replace NAs with half of the row's minimal (non-missing) value.

simulate

For plotChromPeakDensity: logical(1) whether a correspondence analysis should be simulated based on the available data and the provided PeakDensityParam() param argument. See section Correspondence analysis for details.

Value

See help of the individual functions.

Creation of objects

Objects can be created with the contructor function XChromatogram and XChromatograms, respectively. Also, they can be coerced from Chromatogram or Chromatograms() objects using as(object, "XChromatogram") or as(object, "XChromatograms").

Accessing data

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.

Plotting and visualizing

Filtering and subsetting

Chromatographic peak detection

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.

Correspondence analysis

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.

Note

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.

Author(s)

Johannes Rainer

See Also

findChromPeaks-centWave for peak detection on Chromatograms() objects.

Examples

  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
## ---- 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)

## Load test files and extract chromatograms for a data slice
od <- readMSData(c(system.file("cdf/KO/ko15.CDF", package = "faahKO"),
    system.file("cdf/KO/ko16.CDF", package = "faahKO"),
    system.file("cdf/KO/ko18.CDF", package = "faahKO")),
    mode = "onDisk")

## 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, 3))
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)

yclement/xcms documentation built on April 10, 2020, 12:08 a.m.

Related to XChromatogram in yclement/xcms...

yclement/xcms index
README.md

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close