MChromatograms-class {MSnbase} | R Documentation

## Container for multiple Chromatogram objects

### Description

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

`MChromatograms`: create an instance of class `MChromatograms`.

`MChromatograms` objects can, just like a `matrix`, be subsetted using the `[` method. Single elements, rows or columns can be replaced using e.g. `x[1, 1] <- value` where `value` has to be a `Chromatogram` object or a `list` of such objects.

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

`phenoData`: accesses the phenotypical desccription of the samples. Returns an `AnnotatedDataFrame` object.

`pData`: accesses the phenotypical description of the samples. Returns a `data.frame`.

`pData<-`: replace the phenotype data.

`$` and `$<-`: get or replace individual columns of the object's pheno data.

`colnames<-`: replace or set the column names of the `MChromatograms` object. Does also set the `rownames` of the `phenoData`.

`sampleNames`: get the sample names.

`sampleNames<-`: replace or set the sample names of the `MChromatograms` object (i.e. the `rownames` of the pheno data and `colnames` of the data matrix.

`isEmpty`: returns `TRUE` if the `MChromatograms` object or all of its `Chromatogram` objects is/are empty or contain only `NA` intensities.

`featureNames`: returns the feature names of the `MChromatograms` object.

`featureNames<-`: set the feature names.

`featureData`: return the feature data.

`featureData<-`: replace the object's feature data.

`fData`: return the feature data as a `data.frame`.

`fData<-`: replace the object's feature data by passing a `data.frame`

`fvarLabels`: return the feature data variable names (i.e. column names).

`rownames<-`: replace the rownames (and featureNames) of the object.

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

`mz`: returns the m/z for each row of the `MChromatograms` object as a two-column `matrix` (with columns `"mzmin"` and `"mzmax"`).

`polarity`: returns the polarity of the scans/chromatograms: '1', '0' or '-1' for positive, negative or unknown polarity.

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

### 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(object, binSize = 0.5, breaks = numeric(), fun = max)

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

### Arguments

`data` | A `list` of `Chromatogram` objects.
`phenoData` | either a `data.frame`, `AnnotatedDataFrame` or `AnnotatedDataFrame` describing the phenotypical information of the samples.
`featureData` | either a `data.frame` or `AnnotatedDataFrame` with additional information for each row of chromatograms.
`...` | Additional parameters to be passed to the `matrix` constructor, such as `nrow`, `ncol` and `byrow`.
`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.

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

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

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

### Note

Subsetting with `[` will always return a `MChromatograms` object (with the exception of extracting a single element) unless `drop = TRUE` is specified. This is different from the default subsetting behaviour of `matrix`-like objects.

### Author(s)

Johannes Rainer

### See Also

`Chromatogram` for the class representing chromatogram data. `chromatogram` for the method to extract a `MChromatograms` object from a `MSnExp` or `OnDiskMSnExp` 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)

    ## 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.15.7 Index]