QFeatures {QFeatures} | R Documentation

## Quantitative MS QFeatures

### Description

Conceptually, a `QFeatures` object holds a set of assays, each composed of a `matrix` (or `array`) containing quantitative data and row annotations (meta-data). The number and the names of the columns (samples) must always be the same across the assays, but the number and the names of the rows (features) can vary. The assays are typically defined as `SummarizedExperiment` objects. In addition, a `QFeatures` object also uses a single `DataFrame` to annotate the samples (columns) represented in all the matrices.

The `QFeatures` class extends the MultiAssayExperiment::MultiAssayExperiment and inherits all the functionality of the MultiAssayExperiment::MultiAssayExperiment class.

A typical use case for such `QFeatures` object is to represent quantitative proteomics (or metabolomics) data, where different assays represent quantitation data at the PSM (the main assay), peptide and protein level, and where peptide values are computed from the PSM data, and the protein-level data is calculated based on the peptide-level values. The largest assay (the one with the highest number of features, PSMs in the example above) is considered the main assay.

The recommended way to create `QFeatures` objects is the use the `readQFeatures()` function, that creates an instance from tabular data. The `QFeatures` constructor can be used to create objects from their bare parts. It is the user's responsability to make sure that these match the class validity requirements.

### Usage

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

    ## S4 method for signature 'QFeatures,ANY,ANY,ANY'
    x[i, j, ..., drop = TRUE]

    ## S4 method for signature 'QFeatures'
    dims(x)

    ## S4 method for signature 'QFeatures,character,ANY,ANY'
    x[i, j, k, ..., drop = TRUE]

    ## S4 method for signature 'QFeatures'
    rowData(x, use.names = TRUE, ...)

    selectRowData(x, rowvars)

    rowDataNames(x)

    ## S4 replacement method for signature 'QFeatures,character'
    names(x) <- value

    longFormat(object, colDataCols = NULL, rowDataCols = NULL, index = 1L)

    replaceRowDataCols(object, replacement)

    removeRowDataCols(object, i, rowDataCols)

    QFeatures(..., assayLinks = NULL)

    addAssay(x, y, name = "newAssay", assayLinks = AssayLinks(names = name))

### Arguments

`object` | An instance of class `QFeatures`.
`x` | An instance of class QFeatures.
`i` | `character()`, `integer()`, `logical()` or `GRanges()` object for subsetting by rows.
`j` | `character()`, `logical()`, or `numeric()` vector for subsetting by `colData` rows.
`...` | See `MultiAssayExperiment` for details.
`drop` | logical (default `TRUE`) whether to drop empty assay elements in the `ExperimentList`.
`k` | `character()`, `logical()`, or `numeric()` vector for subsetting by assays
`use.names` | A `logical(1)` indicating whether the rownames of each assay should be propagated to the corresponding `rowData`.
`rowvars` | A `character()` with the names of the `rowData` variables (columns) to retain in any assay. All other variables will be dropped. In case an element in `rowvars` isn't found in any `rowData` variable, a message is printed.
`value` | A character() with new name(s) for the assay(s) in `x`
`colDataCols` | A `character()`, `logical()`, or `numeric()` index for colData columns to be included.
`rowDataCols` | A `character()` with column names of the rowData.
`index` | The assay indicator for `SummarizedExperiment` objects. A vector input is supported in the case that the `SummarizedExperiment` object(s) has more than one assay (default `1L`)
`replacement` | A `list()` of same length as `i`. The elements of `value` must be named after `i`. Each element should contain the replacement values to insert in the rowData. If `length(r) > 1`, each element should be a table with the same rows as its corresponding assay and contain the `rowDataCols` variable(s). Set `replacement = NULL` to remove the `rowDataCols`.
`assayLinks` | An optional AssayLinks.
`y` | A single assay or a named list of assays.
`name` | A `character(1)` naming the single assay (default is `"newAssay"`). Ignored if `y` is a list of assays.

### Value

See individual method description for the return value.

### Constructors

- `QFeatures(..., assayLinks)` allows the manual construction of objects. It is the user's responsability to make sure these comply. The arguments in `...` are those documented in `MultiAssayExperiment::MultiAssayExperiment()`. For details about `assayLinks`, see AssayLinks. An example is shown below.

- The `readQFeatures()` function constructs a `QFeatures` object from text-based spreadsheet or a `data.frame` used to generate an assay. See the function manual page for details and an example.

### Accessors

- The `QFeatures` class extends the MultiAssayExperiment::MultiAssayExperiment class and inherits all its accessors and replacement methods.

- The `rowDataNames` accessor returns a list with the `rowData` variable names.

- The `longFormat` accessor takes a `QFeatures` object and returns it in a long format `DataFrame`. Each quantitative value is reported on a separate line. `colData` and `rowData` data can also be added. This function is an extension of the `longFormat` function in the MultiAssayExperiment::MultiAssayExperiment.

### Adding assays

- The `aggregateFeatures()` function creates a new assay by aggregating features of an existing assay.

- `addAssay(x, y, name, assayLinks)`: Adds a new assay (or list of assays) `y` to the `QFeatures` instance `x`. `name` is a `character(1)` naming the single assay (default is `"newAssay"`), and is ignored if `y` is a list of assays. `assayLinks` is an optional AssayLinks.

### Subsetting

- QFeatures object can be subset using the `x[i, j, k, drop = TRUE]` paradigm. See the argument descriptions for details.

- The `subsetByFeature()` function can be used to subset a `QFeatures` object using one or multiple feature names that will be matched across different assays, taking the aggregation relation between assays.

- The `selectRowData(x, rowvars)` function can be used to select a limited number of `rowData` columns of interest named in `rowvars` in the `x` instance of class `QFeatures`.

### Manipulating assays

- The `replaceRowDataCols` function replaces one or more columns in the `rowData` of one or more assays. Note that if the column to replace does not exist, a new column will get added to the `rowData`.

- The `removeRowDataCols` function removes one or more columns in the `rowData` of one or more assays. If the column to remove does not exist in one of the assays, the `rowData` of that assay will stay unchanged.

### Author(s)

Laurent Gatto

### See Also

- The `readQFeatures()` constructor and the `aggregateFeatures()` function. The QFeatures vignette provides an extended example.

- The QFeatures-filtering manual page demonstrates how to filter features based on their rowData.

- The missing-data manual page to manage missing values in `QFeatures` objects.

- The QFeatures-processing and `aggregateFeatures()` manual pages and Processing vignette describe common quantitative data processing methods using in quantitative proteomics.

### Examples

    ## ------------------------
    ## An empty QFeatures object
    ## ------------------------

    QFeatures()

    ## -----------------------------------
    ## Creating a QFeatures object manually
    ## -----------------------------------

    ## two assays (matrices) with matching column names
    m1 <- matrix(1:40, ncol = 4)
    m2 <- matrix(1:16, ncol = 4)
    sample_names <- paste0("S", 1:4)
    colnames(m1) <- colnames(m2) <- sample_names
    rownames(m1) <- letters[1:10]
    rownames(m2) <- letters[1:4]

    ## two corresponding feature metadata with appropriate row names
    df1 <- DataFrame(Fa = 1:10, Fb = letters[1:10],
                     row.names = rownames(m1))
    df2 <- DataFrame(row.names = rownames(m2))

    (se1 <- SummarizedExperiment(m1, df1))
    (se2 <- SummarizedExperiment(m2, df2))

    ## Sample annotation (colData)
    cd <- DataFrame(Var1 = rnorm(4),
                    Var2 = LETTERS[1:4],
                    row.names = sample_names)

    el <- list(assay1 = se1, assay2 = se2)
    fts1 <- QFeatures(el, colData = cd)
    fts1
    fts1[[1]]
    fts1[["assay1"]]

    ## Rename assay
    names(fts1) <- c("se1", "se2")

    ## Add an assay
    fts1 <- addAssay(fts1, se1[1:2, ], name = "se3")

    ## Get the assays feature metadata
    rowData(fts1)

    ## Keep only the Fa variable
    selectRowData(fts1, rowvars = "Fa")

    ## -----------------------------------
    ## See ?readQFeatures to create a
    ## QFeatures object from a data.frame
    ## or spreadsheet.
    ## -----------------------------------

[Package QFeatures version 1.2.0 Index]