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

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

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

### 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, replicate measurements are averaged (by default), and columns are aligned by the row order in `colData`. Additional arguments can be passed on 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.

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

### 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 colData columns with the `colDataCols` argument (`MultiAssayExperiment` method only). The `i` argument allows the user to specify the assay value in a SummarizedExperiment. It directly relates to the `i` argument in the assay method.

### 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. Optionally, `colData` columns can be added to the wide data output (see the `colDataCols` argument). Metadata columns are generated based on the names produced in the wide format DataFrame. These can be accessed via the mcols function. See the `Arguments` and `longFormat` sections for argument descriptions.

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

[Package MultiAssayExperiment version 1.14.0 Index]