R: Container for multiple Chromatogram objects

MChromatograms {MSnbase}

R Documentation

Container for multiple Chromatogram objects

Description

The MChromatograms class allows to store Chromatogram() objects in a matrix-like two-dimensional structure.

Usage

MChromatograms(data, phenoData, featureData, ...)

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

## S4 method for signature 'MChromatograms,ANY,ANY,ANY'
x[i, j, drop = FALSE]

## S4 replacement method for signature 'MChromatograms'
x[i, j] <- value

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

## S4 method for signature 'MChromatograms'
phenoData(object)

## S4 method for signature 'MChromatograms'
pData(object)

## S4 replacement method for signature 'MChromatograms,data.frame'
pData(object) <- value

## S4 method for signature 'MChromatograms'
x$name

## S4 replacement method for signature 'MChromatograms'
x$name <- value

## S4 replacement method for signature 'MChromatograms'
colnames(x) <- value

## S4 method for signature 'MChromatograms'
sampleNames(object)

## S4 replacement method for signature 'MChromatograms,ANY'
sampleNames(object) <- value

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

## S4 method for signature 'MChromatograms'
featureNames(object)

## S4 replacement method for signature 'MChromatograms'
featureNames(object) <- value

## S4 method for signature 'MChromatograms'
featureData(object)

## S4 replacement method for signature 'MChromatograms,ANY'
featureData(object) <- value

## S4 method for signature 'MChromatograms'
fData(object)

## S4 replacement method for signature 'MChromatograms,ANY'
fData(object) <- value

## S4 method for signature 'MChromatograms'
fvarLabels(object)

## S4 replacement method for signature 'MChromatograms'
rownames(x) <- value

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

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

## S4 method for signature 'MChromatograms'
mz(object)

## S4 method for signature 'MChromatograms'
polarity(object)

## S4 method for signature 'MChromatograms'
bin(x, binSize = 0.5, breaks = numeric(), fun = max)

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

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

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

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

## S4 method for signature 'MChromatograms'
c(x, ...)

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

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

Arguments

`data`	for `MChromatograms`: a `list` of `Chromatogram()` objects.
`phenoData`	for `MChromatograms`: either a `data.frame`, `AnnotatedDataFrame` describing the phenotypical information of the samples.
`featureData`	for `MChromatograms`: either a `data.frame` or `AnnotatedDataFrame` with additional information for each row of chromatograms.
`...`	for `MChromatograms`: additional parameters to be passed to the `matrix` constructor, such as `nrow`, `ncol` and `byrow`. For `compareChromatograms`: ignored.
`object`	a `MChromatograms` object.
`x`	for all methods: a `MChromatograms` object.
`i`	for `[`: `numeric`, `logical` or `character` defining which row(s) to extract.
`j`	for `[`: `numeric`, `logical` or `character` defining which columns(s) to extract.
`drop`	for `[`: `logical(1)` whether to drop the dimensionality of the returned object (if possible). The default is `drop = FALSE`, i.e. each subsetting returns a `MChromatograms` object (or a `Chromatogram` object if a single element is extracted).
`value`	for `[<-`: the replacement object(s). Can be a `list` of [Chromatogram()`objects or, if length of`i`and`j`are 1, a single`Chromatogram' object. For `pData<-`: a `data.frame` with the number of rows matching the number of columns of `object`. For `colnames`: a `character` with the new column names.
`col`	for `plot`: the color to be used for plotting. Either a vector of length 1 or equal to `ncol(x)`.
`lty`	for `plot`: the line type (see `plot` in the `graphics` package for more details). Can be either a vector of length 1 or of length equal to `ncol(x)`.
`type`	for `plot`: the type of plot (see `plot` from the `graphics` package for more details). Can be either a vector of length 1 or of length equal to `ncol(x)`.
`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.
`name`	for `$`, the name of the pheno data column.
`binSize`	for `bin`: `numeric(1)` with the size of the bins (in seconds).
`breaks`	For `bin`: `numeric` defining the bins. Usually not required as the function calculates the bins automatically based on `binSize` and the retention time range of chromatograms in the same row.
`fun`	for `bin`: function to be used to aggregate the intensity values falling within each bin.
`all`	for `clean`: `logical(1)` whether all 0-intensities should be removed (`all = TRUE`), or whether 0-intensities adjacent to peaks should be kept (`all = FALSE`; default).
`na.rm`	for `clean`: `logical(1)` whether all `NA` intensities should be removed prior to clean 0-intensity data points.
`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`: alignment methods (see documentation for `alignRt` in the `Chromatogram()` help page. Defaults to `method = "closest"`.
`intensity`	for `filterIntensity`: `numeric(1)` or `function` to use to filter intensities. See description for details.
`y`	for `alignRt`: a `Chromatogram()` object 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`.
`FUNARGS`	for `compareChromatograms`: `list` with additional parameters for `FUN`. Defaults to `FUNARGS = list(use = "pairwise.complete.obs")`.

Details

The MChromatograms class extends the base matrix class and hence allows to store Chromatogram() objects in a two-dimensional array. Each row is supposed to contain Chromatogram objects for one MS data slice with a common m/z and rt range. Columns contain Chromatogram objects from the same sample.

Value

For [: the subset of the MChromatograms object. If a single element is extracted (e.g. if i and j are of length 1) a Chromatogram() object is returned. Otherwise (if drop = FALSE, the default, is specified) a MChromatograms object is returned. If drop = TRUE is specified, the method returns a list of Chromatogram objects.

For `phenoData`: an `AnnotatedDataFrame` representing the
pheno data of the object.

For `pData`: a `data.frame` representing the pheno data of
the object.

For `$`: the value of the corresponding column in the pheno data
table of the object.

For all other methods see function description.

Object creation

MChromatograms are returned by a chromatogram() function from an MSnExp or OnDiskMSnExp. Alternatively, the MChromatograms constructor function can be used.

Data access

$ and $<-: get or replace individual columns of the object's phenodata.
colnames and colnames<-: replace or set the column names of the MChromatograms object. Does also set the rownames of the phenoData.
fData: return the feature data as a data.frame.
fData<-: replace the object's feature data by passing a data.frame.
featureData: return the feature data.
featureData<-: replace the object's feature data.
featureNames: returns the feature names of the MChromatograms object.
featureNames<-: set the feature names.
fvarLabels: return the feature data variable names (i.e. column names).
isEmpty: returns TRUE if the MChromatograms object or all of its Chromatogram objects is/are empty or contain only NA intensities.
mz: returns the m/z for each row of the MChromatograms object as a two-column matrix (with columns "mzmin" and "mzmax").
pData: accesses the phenotypical description of the samples. Returns a data.frame.
pData<-: replace the phenotype data.
phenoData: accesses the phenotypical description of the samples. Returns an AnnotatedDataFrame object.
polarity: returns the polarity of the scans/chromatograms: 1, 0 or -1 for positive, negative or unknown polarity.
precursorMz: return the precursor m/z from the chromatograms. The method returns a matrix with 2 columns ("mzmin" and "mzmax") and as many rows as there are rows in the MChromatograms object. Each row contains the precursor m/z of the chromatograms in that row. An error is thrown if the chromatograms within one row have different precursor m/z values.
productMz: return the product m/z from the chromatograms. The method returns a matrix with 2 columns ("mzmin" and "mzmax") and as many rows as there are rows in the MChromatograms object. Each row contains the product m/z of the chromatograms in that row. An error is thrown if the chromatograms within one row have different product m/z values.
rownames<-: replace the rownames (and featureNames) of the object.

Data subsetting, combining and filtering

[ subset (similar to a matrix) by row and column (with parameters i and j).
[<- replace individual or multiple elements. value has to be either a single Chromatogram obhect or a list of Chromatogram objects.
c concatenate (row-wise) MChromatogram objects with the same number of samples (columns).
filterIntensity: filter each Chromatogram() object within the MChromatograms removing data points with intensities below the 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 the filterIntensity documentation in the Chromatogram() help page for details and examples.

Data processing and manipulation

alignRt: align all chromatograms in an MChromatograms object against the chromatogram specified with y. See documentation on alignRt in the Chromatogram() help page.
bin: aggregates intensity values of chromatograms in discrete bins along the retention time axis. By default, individual Chromatogram objects of one row are binned into the same bins. The function returns a MChromatograms object with binned chromatograms.
clean: removes 0-intensity data points. Either all of them (with all = TRUE) or all except those adjacent to non-zero intensities (all = FALSE; default). See clean() documentation for more details and examples.
compareChromatograms: calculates pairwise similarity score between chromatograms in x and y. If y is missing, a pairwise comparison is performed between all chromatograms in x. See documentation on compareChromatograms in the Chromatogram() help page 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.

Data visualization

plot: plots a MChromatograms object. For each row in the object one plot is created, i.e. all Chromatogram() objects in the same row are added to the same plot. If nrow(x) > 1 the plot area is split into nrow(x) sub-plots and the chromatograms of one row are plotted in each.

Author(s)

Johannes Rainer

Examples

## Creating some chromatogram objects to put them into a MChromatograms object
ints <- abs(rnorm(25, sd = 200))
ch1 <- Chromatogram(rtime = 1:length(ints), ints)
ints <- abs(rnorm(32, sd = 90))
ch2 <- Chromatogram(rtime = 1:length(ints), ints)
ints <- abs(rnorm(19, sd = 120))
ch3 <- Chromatogram(rtime = 1:length(ints), ints)
ints <- abs(rnorm(21, sd = 40))
ch4 <- Chromatogram(rtime = 1:length(ints), ints)

## Create a MChromatograms object with 2 rows and 2 columns
chrs <- MChromatograms(list(ch1, ch2, ch3, ch4), nrow = 2)
chrs

## Extract the first element from the second column. Extracting a single
## element always returns a Chromatogram object.
chrs[1, 2]

## Extract the second row. Extracting a row or column (i.e. multiple elements
## returns by default a list of Chromatogram objects.
chrs[2, ]

## Extract the second row with drop = FALSE, i.e. return a MChromatograms
## object.
chrs[2, , drop = FALSE]

## Replace the first element.
chrs[1, 1] <- ch3
chrs

## Add a pheno data.
pd <- data.frame(name = c("first sample", "second sample"),
    idx = 1:2)
pData(chrs) <- pd

## Column names correspond to the row names of the pheno data
chrs

## Access a column within the pheno data
chrs$name

## Access the m/z ratio for each row; this will be NA for the present
## object
mz(chrs)


## Data visualization

## Create some random Chromatogram objects
ints <- abs(rnorm(123, mean = 200, sd = 32))
ch1 <- Chromatogram(rtime = seq_along(ints), intensity = ints, mz = 231)
ints <- abs(rnorm(122, mean = 250, sd = 43))
ch2 <- Chromatogram(rtime = seq_along(ints), intensity = ints, mz = 231)
ints <- abs(rnorm(125, mean = 590, sd = 120))
ch3 <- Chromatogram(rtime = seq_along(ints), intensity = ints, mz = 542)
ints <- abs(rnorm(124, mean = 1200, sd = 509))
ch4 <- Chromatogram(rtime = seq_along(ints), intensity = ints, mz = 542)

## Combine into a 2x2 MChromatograms object
chrs <- MChromatograms(list(ch1, ch2, ch3, ch4), byrow = TRUE, ncol = 2)

## Plot the second row
plot(chrs[2, , drop = FALSE])

## Plot all chromatograms
plot(chrs, col = c("#ff000080", "#00ff0080"))

[Package MSnbase version 2.20.1 Index]