XChromatogram: Containers for chromatographic and peak detection data

In sneumann/xcms: LC-MS and GC-MS Data Analysis

Containers for chromatographic and peak detection data

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 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.

Usage

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 'XChromatogram'
filterChromPeaks(object, method = c("keepTop"), ...)

## S4 method for signature 'XChromatogram'
transformIntensity(object, FUN = identity)

## 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 = TRUE]

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

## S4 method for signature 'XChromatograms'
filterChromPeaks(object, method = c("keepTop"), ...)

## S4 method for signature 'XChromatograms'
transformIntensity(object, FUN = identity)

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 filterChromPeaks: additional parameters defining how to filter chromatographic peaks. See function description below for details.
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.
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"). For filterChromPeaks: character(1) defining the method that should be used to filter chromatographic peaks. See help on filterChromPeaks below for details.
FUN	For transformIntensity: a function to transform the intensity values of object.
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). Defaults to drop = TRUE, thus, if length of i and j is 1 a XChromatogram is returned. Note that drop is ignored if length of i or j is larger than 1, thus a XChromatograms is returned.
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 MChromatograms() objects using as(object, "XChromatogram") or as(object, "XChromatograms").

Filtering and subsetting

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.

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.

• 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.

• filterChromPeaks: filters chromatographic peaks in object depending on parameter method and method-specific parameters passed as additional arguments with .... Available methods are:

  • method = "keepTop": keep top n (default n = 1L) peaks in each chromatogram ordered by column order (defaults to order = "maxo"). Parameter decreasing (default decreasing = TRUE) can be used to order peaks in descending (decreasing = TRUE) or ascending ( decreasing = FALSE) order to keep the top n peaks with largest or smallest values, respectively.

• 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.

Manipulating data

• transformIntensity: transforms the intensity values of the chromatograms with provided function FUN. See transformIntensity() in the MSnbase package for details. For XChromatogram and XChromatograms in addition to the intensity values also columns "into" and "maxo" in the object's chromPeaks matrix are transformed by the same function.

Plotting and visualizing

• 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.

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 MChromatograms() objects.

Examples

## ---- Creation of XChromatograms ----
##
## Create a XChromatograms from Chromatogram objects
library(MSnbase)
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
faahko_sub <- loadXcmsData("faahko_sub2")

## Subset the dataset to the first and third file.
xod_sub <- filterFile(faahko_sub, file = c(1, 3))

od <- as(xod_sub, "MsExperiment")

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

library(MSnbase)
## 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)

sneumann/xcms documentation built on Nov. 23, 2024, 6:53 p.m.