MultiAssayExperiment-helpers {MultiAssayExperiment} | R Documentation

## A group of helper functions for manipulating and cleaning a MultiAssayExperiment

### Description

A set of helper functions were created to help clean and manipulate a MultiAssayExperiment object. `intersectRows` also works for `ExperimentList` objects.

- complete.cases: Returns a logical vector corresponding to 'colData' rows that have data across all experiments

- isEmpty: Returns a logical `TRUE` value for zero length `MultiAssayExperiment` objects

- intersectRows: Takes all common rows across experiments, excludes experiments with empty rownames

- intersectColumns: A wrapper for `complete.cases` to return a `MultiAssayExperiment` with only those biological units that have measurements across all experiments

- replicated: A function that identifies multiple samples that originate from a single biological unit within each assay

- anyReplicated: Displays which assays have replicate measurements

- mergeReplicates: A function that combines replicated / repeated measurements across all experiments and is guided by the replicated return value

- longFormat: A `MultiAssayExperiment` method that returns a small and skinny DataFrame. The `colDataCols` arguments allows the user to append `colData` columns to the data.

- wideFormat: A function to return a wide DataFrame where each row represents an observation. Optional `colDataCols` can be added when using a `MultiAssayExperiment`.

- hasRowRanges: A function that identifies ExperimentList elements that have a rowRanges method

- getWithColData: A convenience function for extracting an assay and associated colData

- renamePrimary: A convenience function to rename the primary biological units as represented in the `rownames(colData)`

- renameColname: A convenience function to rename the colnames of a particular assay

### Usage

    ## S4 method for signature 'MultiAssayExperiment'
    complete.cases(...)

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

    intersectRows(x)

    intersectColumns(x)

    replicated(x)

    ## S4 method for signature 'MultiAssayExperiment'
    replicated(x)

    anyReplicated(x)

    ## S4 method for signature 'MultiAssayExperiment'
    anyReplicated(x)

    mergeReplicates(x, replicates = list(), simplify = BiocGenerics::mean, ...)

    ## S4 method for signature 'MultiAssayExperiment'
    mergeReplicates(
      x,
      replicates = replicated(x),
      simplify = BiocGenerics::mean,
      ...
    )

    ## S4 method for signature 'ANY'
    mergeReplicates(x, replicates = list(), simplify = BiocGenerics::mean, ...)

    longFormat(object, colDataCols = NULL, i = 1L)

    wideFormat(
      object,
      colDataCols = NULL,
      check.names = TRUE,
      collapse = "_",
      i = 1L
    )

    hasRowRanges(x)

    ## S4 method for signature 'MultiAssayExperiment'
    hasRowRanges(x)

    ## S4 method for signature 'ExperimentList'
    hasRowRanges(x)

    getWithColData(x, i, mode = c("append", "replace"), verbose = FALSE)

    renamePrimary(x, value)

    renameColname(x, i, value)

    splitAssays(x, hitList)

    ## S4 method for signature 'MultiAssayExperiment'
    splitAssays(x, hitList)

    makeHitList(x, patternList)

### Arguments

`...` | Additional arguments. See details for more information.
`x` | A MultiAssayExperiment or ExperimentList
`replicates` | A list of LogicalLists indicating multiple / duplicate entries for each biological unit per assay, see `replicated` (default `replicated(x)`).
`simplify` | A function for merging repeat measurements in experiments as indicated by the `replicated` method for `MultiAssayExperiment`
`object` | Any supported class object
`colDataCols` | A `character`, `logical`, or `numeric` index for `colData` columns to be included
`i` | longFormat: The i-th assay in SummarizedExperiment-like objects. A vector input is supported in the case that the SummarizedExperiment object(s) has more than one assay (default 1L), renameColname: Either a `numeric` or `character` index indicating the assay whose colnames are to be renamed
`check.names` | (logical default TRUE) Column names of the output `DataFrame` will be checked for syntactic validity and made unique, if necessary
`collapse` | (character default "_") A single string delimiter for output column names. In `wideFormat`, experiments and rownames (and when replicate samples are present, colnames) are seperated by this delimiter
`mode` | String indicating how MultiAssayExperiment column-level metadata should be added to the SummarizedExperiment `colData`.
`verbose` | logical(1) Whether to 'suppressMessages' on subsetting operations in 'getWithColData' (default FALSE)
`value` | renamePrimary: A `character` vector of the same length as the existing `rownames(colData)` to use for replacement, renameColname: A `CharacterList` or `list` with matching `lengths` to replace `colnames(x)`
`hitList` | a named `list` or `List` of logical vectors that indicate groupings in the assays
`patternList` | a named `list` or `List` of atomic character vectors that are the input to `grepl` for identifying groupings in the assays

### Details

The `replicated` function finds replicate measurements in each assay and returns a list of LogicalLists. Each element in a single LogicalList corresponds to a biological or primary unit as in the `sampleMap`. Below is a small graphic for one particular biological unit in one assay, where the logical vector corresponds to the number of measurements/samples in the assay:

     >      replicated(MultiAssayExperiment)
     (list str)       '-- $ AssayName
     (LogicalList str)      '-- [[ "Biological Unit" ]]
     Replicated if sum(...) > 1          '-- TRUE TRUE FALSE FALSE

`anyReplicated` determines if any of the assays have at least one replicate. Note. These methods are not available for the `ExperimentList` class due to a missing `sampleMap` structure (by design).

The `mergeReplicates` function is a house-keeping method for a `MultiAssayExperiment` where only `complete.cases` are returned. This by-assay operation averages replicate measurements (by default) and columns are aligned by the row order in `colData`. Users can provide their own function for merging replicates with the `simplify` functional argument. Additional inputs `...` are sent to the 'simplify' function.

The `mergeReplicates` "ANY" method consolidates duplicate measurements for rectangular data structures, returns object of the same class (endomorphic). The ellipsis or `...` argument allows the user to provide additional arguments to the `simplify` functional argument.

The `longFormat` "ANY" class method, works with classes such as ExpressionSet and SummarizedExperiment as well as `matrix` to provide a consistent long and skinny DataFrame.

The `hasRowRanges` method identifies assays that support a rowRanges method and return a GRanges object.

### Value

See the itemized list in the description section for details.

### mergeReplicates

The `mergeReplicates` function makes use of the output from `replicated` which will point out the duplicate measurements by biological unit in the `MultiAssayExperiment`. This function will return a `MultiAssayExperiment` with merged replicates. Additional arguments can be provided to the simplify argument via the ellipsis (...). For example, when replicates "TCGA-B" and "TCGA-A" are found in the assay, the name of the first appearing replicate is taken (i.e., "B"). Note that a typical use case of merging replicates occurs when there are multiple measurements on the same sample (within the same assay) and can therefore be averaged.

### longFormat

The 'longFormat' method takes data from the `ExperimentList` in a `MultiAssayExperiment` and returns a uniform `DataFrame`. The resulting DataFrame has columns indicating primary, rowname, colname and value. This method can optionally include columns of the MultiAssayExperiment colData named by `colDataCols` character vector argument. (`MultiAssayExperiment` method only). The `i` argument allows the user to specify the assay value for the SummarizedExperiment assay function's `i` argument.

### wideFormat

The `wideFormat` function returns standardized wide DataFrame where each row represents a biological unit as in the `colData`. Depending on the data and setup, biological units can be patients, tumors, specimens, etc. Metadata columns are generated based on the names produced in the wide format DataFrame. These can be accessed via the mcols function. See the `wideFormat` section for description of the `colDataCols` and `i` arguments.

### hasRowRanges

The `hasRowRanges` method identifies assays with associated ranged row data by directly testing the method on the object. The result from the test must be a GRanges class object to satisfy the test.

### getWithColData

The `getWithColData` function allows the user to conveniently extract a particular assay as indicated by the `i` index argument. It will also attempt to provide the `colData` along with the extracted object using the `colData<-` replacement method when possible. Typically, this method is available for SummarizedExperiment and `RaggedExperiment` classes.

The setting of `mode` determines how the `colData` is added. If `mode="append"`, the MultiAssayExperiment metadata is appended onto that of the SummarizedExperiment. If any fields are duplicated by name, the values in the SummarizedExperiment are retained, with a warning emitted if the values are different. For `mode="replace"`, the MultiAssayExperiment metadata replaces that of the SummarizedExperiment, while for `mode="none"`, no replacement or appending is performed.

### rename*

The `renamePrimary` function allows the user to conveniently change the actual names of the primary biological units as seen in `rownames(colData)`. `renameColname` allows the user to change the names of a particular assay based on index `i`. `i` can either be a single numeric or character value. See `colnames<-` method for renaming multiple colnames in a `MultiAssayExperiment`.

### splitAssays

The `splitAssays` method separates columns in each of the assays based on the `hitList` input. The `hitList` can be generated using the `makeHitList` helper function. To use the `makeHitList` helper, the user should input a list of patterns that will match on the column names of each assay. These matches should be mutually exclusive as to avoid repetition of columns across assays. See the examples section.

### Examples

    example(MultiAssayExperiment)

    complete.cases(mae)

    isEmpty(MultiAssayExperiment())

    ## renaming biological units (primary)

    mae2 <- renamePrimary(mae, paste0("pt", 1:4))
    colData(mae2)
    sampleMap(mae2)

    ## renaming observational units (colname)

    mae2 <- renameColname(mae, i = "Affy", paste0("ARRAY", 1:4))
    colnames(mae2)
    sampleMap(mae2)

    patts <- list(
        normals = "TCGA-OR-[A-Z0-9]{4}-11",
        tumors = "TCGA-OR-[A-Z0-9]{4}-01"
    )

    hits <- makeHitList(miniACC, patts)

    splitAssays(miniACC, hits)

[Package MultiAssayExperiment version 1.20.0 Index]