MChromatograms-class: Container for multiple Chromatogram objects

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

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,ANY,ANY,ANY'
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,ANY'
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"),
  ...
)

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

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⁠iandj⁠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 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 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 and returns a similarity matrix with the number of rows corresponding to the number of chromatograms in x and the number of columns to the number of chromatograms in 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.

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

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

See Also

⁠Chromatogram()] for the class representing chromatogram data. [chromatogram()] for the method to extract a ⁠MChromatograms⁠object from a⁠MSnExporOnDiskMSnExp⁠ object. [readSRMData()⁠ for the function to read chromatographic data of an SRM/MRM experiment.

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

## log2 transform intensities
res <- transformIntensity(chrs, log2)
plot(res)

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