Chromatogram-class: Representation of chromatographic MS data

In lgatto/MSnbase: Base Functions and Classes for Mass Spectrometry and Proteomics

Representation of chromatographic MS data

Description

The Chromatogram class is designed to store chromatographic MS data, i.e. pairs of retention time and intensity values. Instances of the class can be created with the Chromatogram constructor function but in most cases the dedicated methods for OnDiskMSnExp and MSnExp objects extracting chromatograms should be used instead (i.e. the chromatogram() method).

Usage

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

aggregationFun(object)

## S4 method for signature 'Chromatogram'
show(object)

## S4 method for signature 'Chromatogram'
rtime(object)

## S4 method for signature 'Chromatogram'
intensity(object)

## S4 method for signature 'Chromatogram'
mz(object, filter = FALSE)

## S4 method for signature 'Chromatogram'
precursorMz(object)

## S4 method for signature 'Chromatogram'
fromFile(object)

## S4 method for signature 'Chromatogram'
length(x)

## S4 method for signature 'Chromatogram'
as.data.frame(x)

## S4 method for signature 'Chromatogram'
filterRt(object, rt)

## S4 method for signature 'Chromatogram'
clean(object, all = FALSE, na.rm = FALSE)

## S4 method for signature 'Chromatogram,ANY'
plot(
  x,
  col = "#00000060",
  lty = 1,
  type = "l",
  xlab = "retention time",
  ylab = "intensity",
  main = NULL,
  ...
)

## S4 method for signature 'Chromatogram'
msLevel(object)

## S4 method for signature 'Chromatogram'
isEmpty(x)

## S4 method for signature 'Chromatogram'
productMz(object)

## S4 method for signature 'Chromatogram'
bin(
  x,
  binSize = 0.5,
  breaks = seq(floor(min(rtime(x))), ceiling(max(rtime(x))), by = binSize),
  fun = max
)

## S4 method for signature 'Chromatogram'
normalize(object, method = c("max", "sum"))

## S4 method for signature 'Chromatogram'
filterIntensity(object, intensity = 0, ...)

## S4 method for signature 'Chromatogram,Chromatogram'
alignRt(x, y, method = c("closest", "approx"), ...)

## S4 method for signature 'Chromatogram,Chromatogram'
compareChromatograms(
  x,
  y,
  ALIGNFUN = alignRt,
  ALIGNFUNARGS = list(),
  FUN = cor,
  FUNARGS = list(use = "pairwise.complete.obs"),
  ...
)

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

Arguments

rtime	for Chromatogram: numeric with the retention times (length has to be equal to the length of intensity).
intensity	for Chromatogram: numeric with the intensity values (length has to be equal to the length of rtime). For filterIntensity: numeric(1) or function to use to filter intensities. See description for details.
mz	for Chromatogram: numeric(2) representing the mz value range (min, max) on which the chromatogram was created. This is supposed to contain the real range of mz values in contrast to filterMz. If not applicable use mzrange = c(0, 0).
filterMz	for Chromatogram: numeric(2) representing the mz 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 Chromatogram: numeric(2) for SRM/MRM transitions. Represents the mz of the precursor ion. See details for more information.
productMz	for Chromatogram: numeric(2) for SRM/MRM transitions. Represents the mz of the product. See details for more information.
fromFile	for Chromatogram: integer(1) the index of the file within the OnDiskMSnExp or MSnExp from which the chromatogram was extracted.
aggregationFun	for Chromatogram: character string specifying the function that was used to aggregate intensity values for the same retention time across the mz range. Supported are "sum" (total ion chromatogram), "max" (base peak chromatogram), "min" and "mean".
msLevel	for Chromatogram: integer(1) with the MS level from which the chromatogram was extracted.
object	Chromatogram object.
filter	for mz: logical(1) defining whether the m/z range to filter the originating object (e.g. MSnExp object) should be returned or the m/z range of the actual data. Defaults to filter = FALSE.
x	Chromatogram object.
rt	for filterRt: numeric(2) defining the lower and upper retention time to which the Chromatogram should be subsetted.
all	for clean: logical(1) whether all 0 intensities should be removed. Defaults to all = FALSE. See clean() for details.
na.rm	for clean: if all NA intensities should be removed before cleaning the Chromatogram. Defaults to clean = FALSE.
col	for plot: the color to be used for plotting.
lty	for plot: the line type. See help page of plot in the graphics package for details.
type	for plot: the type of plot. See help page of plot in the graphics package for details.
xlab	for plot: the x-axis label.
ylab	for plot: the y-axis label.
main	for plot: the plot title. If not provided the mz range will be used as plot title.
...	for plot: additional arguments to be passed to the base plot function. For filterIntensity: additional parameters passed along to the function provided with intensity. For compareChromatograms: ignored
binSize	for bin: numeric(1) with the size of the bins (in seconds). Defaults to binSize = 0.5.
breaks	for bin: numeric defining the bins. Usually not required as the function calculates the bins automatically based on binSize.
fun	for bin: function to be used to aggregate the intensity values falling within each bin. Defaults to fun = max.
method	character(1). For normalise: defining whether each chromatogram should be normalized to its maximum signal (method = "max") or total signal (method = "sum"). For alignRt: aligning approach that should be used (see description). Defaults to method = "closest".
y	for alignRt: Chromatogram against which x should be aligned against.
ALIGNFUN	for compareChromatograms: function to align chromatogram x against chromatogram y. Defaults to alignRt.
ALIGNFUNARGS	list of parameters to be passed to ALIGNFUN.
FUN	for compareChromatograms: function to calculate a similarity score on the intensity values of the compared and aligned chromatograms. Defaults to FUN = cor. For transformIntensity: function to transform chromatograms' intensity values. Defaults to FUN = identity.
FUNARGS	for compareChromatograms: list with additional parameters for FUN. Defaults to FUNARGS = list(use = "pairwise.complete.obs").

Details

The mz, filterMz, precursorMz and productMz are stored as a numeric(2) representing a range even if the chromatogram was generated for only a single ion (i.e. a single mz value). Using ranges for mz values allow this class to be used also for e.g. total ion chromatograms or base peak chromatograms.

The slots `precursorMz` and `productMz` allow to represent SRM
(single reaction monitoring) and MRM (multiple SRM) chromatograms. As
example, a `Chromatogram` for a SRM transition 273 -> 153 will have
a `@precursorMz = c(273, 273)` and a
`@productMz = c(153, 153)`.

Object creation

Chromatogram objects can be extracted from an MSnExp or OnDiskMSnExp object with the chromatogram() function.

Alternatively, the constructor function Chromatogram can be used, which takes arguments rtime, intensity, mz, filterMz, precursorMz, productMz, fromFile, aggregationFun and msLevel.

Data access and coercion

• aggregationFun: gets the aggregation function used to create the Chromatogram.

• as.data.frame: returns a data.frame with columns "rtime" and "intensity".

• fromFile: returns an integer(1) with the index of the originating file.

• intensity: returns the intensities from the Chromatogram.

• isEmpty: returns TRUE if the chromatogram is empty or has only NA intensities.

• length: returns the length (i.e. number of data points) of the Chromatogram.

• msLevel: returns an integer(1) with the MS level of the chromatogram.

• mz: get the m/z (range) from the Chromatogram. The function returns a numeric(2) with the lower and upper boundaries. Parameter filter allows to specify whether the m/z range used to filter the originating object should be returned or the m/z range of the actual data.

• precursorMz: get the m/z of the precursor ion. The function returns a numeric(2) with the lower and upper boundary.

• productMz: get the m/z of the producto chromatogram/ion. The function returns a numeric(2) with the lower and upper m/z value.

• rtime: returns the retention times from the Chromatogram.

Data subsetting and filtering

• filterRt: filter/subset the Chromatogram to the specified retention time range (defined with parameter rt).

• filterIntensity: filter a Chromatogram() object removing data points with intensities below a user provided threshold. If intensity is a numeric value, the returned chromatogram will only contain data points with intensities > intensity. In addition it is possible to provide a function to perform the filtering. This function is expected to take the input Chromatogram (object) and to return a logical vector with the same length then there are data points in object with TRUE for data points that should be kept and FALSE for data points that should be removed. See examples below.

Data processing and manipulation

• alignRt: Aligns chromatogram x against chromatogram y. The resulting chromatogram has the same length (number of data points) than y and the same retention times thus allowing to perform any pair-wise comparisons between the chromatograms. If x is a MChromatograms() object, each Chromatogram in it is aligned against y. Additional parameters (...) are passed along to the alignment functions (e.g. closest()).

  Parameter method allows to specify which alignment method should be used. Currently there are the following options:

  • method = "closest" (the default): match data points in the first chromatogram (x) to those of the second (y) based on the difference between their retention times: each data point in x is assigned to the data point in y with the smallest difference in their retention times if their difference is smaller than the minimum average difference between retention times in x or y (parameter tolerance for the call to the closest() function). By setting tolerance = 0 only exact retention times are matched against each other (i.e. only values are kept with exactly the same retention times between both chromatograms).

  • method = "approx": uses the base R approx function to approximate intensities in x to the retention times in y (using linear interpolation). This should only be used for chromatograms that were measured in the same measurement run (e.g. MS1 and corresponding MS2 chromatograms from SWATH experiments).

• bin: aggregates intensity values from a chromatogram in discrete bins along the retention time axis and returns a Chromatogram object with the retention time representing the mid-point of the bins and the intensity the binned signal. Parameters binSize and breaks allow to define the binning, fun the function which should be used to aggregate the intensities within a bin.

• compareChromatograms: calculates a similarity score between 2 chromatograms after aligning them. Parameter ALIGNFUN allows to define a function that can be used to align x against y (defaults to ALIGNFUN = alignRt). Subsequently, the similarity is calculated on the aligned intensities with the function provided with parameter FUN which defaults to cor (hence by default the Pearson correlation is calculated between the aligned intensities of the two compared chromatograms). Additional parameters can be passed to the ALIGNFUN and FUN with the parameter ALIGNFUNARGS and FUNARGS, respectively.

• clean: removes 0-intensity data points (and NA values). See clean() for details.

• normalize, normalise: normalises the intensities of a chromatogram by dividing them either by the maximum intensity (method = "max") or total intensity (method = "sum") of the chromatogram.

• transformIntensity: allows to manipulate the intensity values of a chromatogram using a user provided function. See below for examples.

Data visualization

• plot: plots a Chromatogram object.

Author(s)

Johannes Rainer

See Also

MChromatograms for combining Chromatogram in a two-dimensional matrix (rows being mz-rt ranges, columns samples). ⁠chromatogram()] for the method to extract chromatogram data from an ⁠MSnExporOnDiskMSnExp⁠object. [clean()] for the method to *clean* a⁠Chromatogram' object.

Examples

## Create a simple Chromatogram object.
ints <- abs(rnorm(100, sd = 100))
rts <- seq_len(length(ints))
chr <- Chromatogram(rtime = rts, intensity = ints)
chr

## Extract intensities
intensity(chr)

## Extract retention times
rtime(chr)

## Extract the mz range - is NA for the present example
mz(chr)

## plot the Chromatogram
plot(chr)

## Create a simple Chromatogram object based on random values.
chr <- Chromatogram(intensity = abs(rnorm(1000, mean = 2000, sd = 200)),
        rtime = sort(abs(rnorm(1000, mean = 10, sd = 5))))
chr

## Get the intensities
head(intensity(chr))

## Get the retention time
head(rtime(chr))

## What is the retention time range of the object?
range(rtime(chr))

## Filter the chromatogram to keep only values between 4 and 10 seconds
chr2 <- filterRt(chr, rt = c(4, 10))

range(rtime(chr2))

## Data manipulations:

## normalize a chromatogram
par(mfrow = c(1, 2))
plot(chr)
plot(normalize(chr, method = "max"))

## Align chromatograms against each other

chr1 <- Chromatogram(rtime = c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10),
    intensity = c(3, 5, 14, 30, 24, 6, 2, 1, 1, 0))
chr2 <- Chromatogram(rtime = c(2.5, 3.42, 4.5, 5.43, 6.5),
    intensity = c(5, 12, 15, 11, 5))

plot(chr1, col = "black")
points(rtime(chr2), intensity(chr2), col = "blue", type = "l")

## Align chr2 to chr1 without interpolation
res <- alignRt(chr2, chr1)
rtime(res)
intensity(res)
points(rtime(res), intensity(res), col = "#00ff0080", type = "l")

## Align chr2 to chr1 with interpolation
res <- alignRt(chr2, chr1, method = "approx")
points(rtime(res), intensity(res), col = "#ff000080", type = "l")
legend("topright", col = c("black", "blue", "#00ff0080","#ff000080"),lty = 1,
    legend = c("chr1", "chr2", "chr2 matchRtime", "chr2 approx"))


## Compare Chromatograms. Align chromatograms with `alignRt` and
## method `"approx"`
compareChromatograms(chr2, chr1, ALIGNFUNARGS = list(method = "approx"))

## Data filtering

chr1 <- Chromatogram(rtime = c(1, 2, 3, 4, 5, 6, 7, 8, 9, 10),
    intensity = c(3, 5, 14, 30, 24, 6, 2, 1, 1, 0))

## Remove data points with intensities below 10
res <- filterIntensity(chr1, 10)
intensity(res)

## Remove data points with an intensity lower than 10% of the maximum
## intensity in the Chromatogram
filt_fun <- function(x, prop = 0.1) {
    x@intensity >= max(x@intensity, na.rm = TRUE) * prop
}
res <- filterIntensity(chr1, filt_fun)
intensity(res)

## Remove data points with an intensity lower than half of the maximum
res <- filterIntensity(chr1, filt_fun, prop = 0.5)
intensity(res)

## log2 transform intensity values
res <- transformIntensity(chr1, log2)
intensity(res)
log2(intensity(chr1))

lgatto/MSnbase documentation built on Nov. 12, 2024, 10:58 a.m.