MultiAssayExperiment API

Warning

This document is not currently up to date. See vignettes for the up to date API.

Executive summary

The MultiAssayExperiment class can be used to manage results of diverse assays on a collection of samples. Currently the class can handle assays that are organized as instances of RangedSummarizedExperiment, ExpressionSet, matrix, RangedRaggedAssay (inherited from GRangesList), and RangedVcfStack (defined in the yriMulti package in bioc-devel). Create new MultiAssayExperiment instances with the eponymous constructor, minimally with the argument ExperimentList, potentially also with the arguments pData and sampleMap.

Other data classes can be used in the MultiAssayExperiment, as long as they provide four methods: colnames(), rownames(), [i, j], and dim(). See the ExperimentList section for details on requirements for incorporating new data classes.

Note: For a brief visual summary of classes and methods involved in the package, please enter API(shiny = TRUE) after loading the package to invoke the API explorer shiny dashboard

Overview

The most important class exported by this package is the MultiAssayExperiment for coordinated representation of multiple experiments on partially overlapping samples, with associated metadata at the level of entire study and the level of "biological unit". The biological unit may be a patient, plant, yeast strain, etc. This package is designed around the following hierarchy of information:

study (highest level). The study can encompass several different types of experiments performed on one set of biological units, for example cancer patients. A MultiAssayExperiment represents a whole study, containing:

1. metadata about the study as a whole
2. metadata about each biological unit: for example, age, grade, stage for cancer patients
3. results from a set of experiments performed on the biological units
4. a map for matching data from the experiments back to the corresponding biological units.

experiment. A set of assays of a single type performed on some or all of the biological units. It is permissible that an experiment may be performed only on a subset of the biological units, and may be performed in duplicate on some of the biological units. For example, an experiment could be somatic mutation calls for some or all of the biological units.

Data from multiple experiments are stored in a list object called the ExperimentList, which provides flexibility for partially overlapping samples (column names) and features (row names), while keeping samples correctly matched to study-level metadata and to other experiments on the same samples.

Experiments may be ID-based, where measurements are indexed identifiers of genes, microRNA, proteins, microbes, etc. Alternatively, experiments may be range-based, where measurements correspond to genomic ranges that can be represented as GRanges objects, such as gene expression or copy number. Note that for ID-based experiments, there is no requirement that the same IDs be present for different experiments. For range-based experiments, there is also no requirement that the same ranges be present for different experiments; furthermore, it is possible for different samples within an experiment to be represented by different ranges. Note however that even ranged-based features must be named, so that genomic features can be referred to by character IDs. The following data classes have so far been tested to work as elements of ExperimentList:

1. matrix: the most basic class for ID-based datasets, could be used for example for gene expression summarized per-gene, microRNA, metabolomics, or microbiome data.
2. ExpressionSet: A richer representation for ID-based datasets, could be used for the same types of data as matrix, but storing additional assay-level metadata.
3. SummarizedExperiment: Another rich representation for ID-based matrix-like datasets
4. RangedSummarizedExperiment: For rectangular range-based datasets, meaning that one set of genomic ranges are assayed for multiple samples. Could be used for gene expression, methylation, or other data types referring to genomic positions.
5. RaggedRangedAssay: For non-rectangular (ragged) ranged-based datasets, meaning that a potentially different set of genomic ranges are assayed for each sample. A typical example would be segmented copy number, where segmentation of copy number alterations occurs and different genomic locations in each sample.
6. RangedVcfStack: For VCF archives broken up by chromosome (see VcfStack class defined in GenomicFiles package)

samples (lowest level). An individual set of measurements performed on a single biological unit. These measurements must be indexed by character IDs, however datasets may be ID-based (such as matrix or ExpressionSet) or range-based (such as RangedSummarizedExperiment). In the experimental datasets, columns refer to samples, and rows refer to genomic features that are represented by IDs or ranges.

MultiAssayExperiment class

Overview

The MultiAssayExperiment class is the main representation of multiple experiment data. It contains all information required to subset and match sample identifiers with clinical records.

Structure

• ExperimentList - slot of class ExperimentList containing data for each experiment/assay
  • contains "SimpleList" class from S4Vectors
  • access using "experiments"
• pData - slot of class DataFrame describing the clinical data available across all experiments
• sampleMap - slot of class DataFrame of translatable identifiers of samples and participants
• metadata - slot of any class providing additional information about the MultiAssayExperiment object
• drops - slot of class list to keep a log of all residuals from subset operations

Validity

1. ExperimentList

2. ExperimentList length should be the same as the unique length of the sampleMap "assay" column.

3. Element names of the ExperimentList should be found in the sampleMap "assay" column.

4. For each ExperimentList element (say for an element named "assay X"), the colnames of that element must be identical to the sorted character string found in the "colname" column of the sampleMap within the rows where the "assay" equals the name of that ExperimentList element (in this example, "assay X"). The order does not need to be the same.

5. pData

6. Ensure that this slot is of class DataFrame

7. sampleMap - validity checks include checks for consistency between the sampleMap and the pData primary (or phenotype) data slot

8. all names in the sampleMap "primary" column must be found in the rownames of the pData DataFrame.

9. Within rows of sampleMap corresponding to a single value in the "assay" column, there can be no duplicated values in the "colname" column.

Note. These validity checks only apply when at least an ExperimentList slot is provided at MultiAssayExperiment object creation.

updateObject method and API changes

The updateObject method attempts to repair previously serialized instances of the MultiAssayExperiment so that it conforms with the updated API. It is advised to run updateObject on old instances of the MultiAssayExperiment and reserialize the object. This should be a one-time operation.

Recent changes to the API include changing the name of the workhorse container class from Elist to ExperimentList with an accessor function named experiments. Other changes include, renaming and reordering of the sampleMap columns from primary, assay, and assayname to assay (previously "assayname"), primary, and colname (previously "assay"), respectively.

# `ExperimentList` class ## Overview

The ExperimentList slot and class is the driver for the MultiAssayExperiment class as it contains necessary data from experiments and sample identifiers. The purpose of the ExperimentList is to store results from a set of experiments, as a SimpleList. Each element in the ExperimentList represents an experiment performed. All ExperimentList elements should be named.

Structure

• ExperimentList - inherits from SimpleList with no additions. Contains separate validity checks and a show method.

Validity

1. ExperimentList elements
2. For data classes stored in each ExperimentList element, ensure that method functions [ (bracket), colnames, rownames, and dim are possible.
3. For each ExperimentList element, ensure that dimensions of non-zero length in each ExperimentList element have non-null rownames and colnames.

Rationale

1. ExperimentList element requirements
2. The requirement of methods [ (bracket), colnames, rownames, and dim allow for predictable subsetting operations and metadata acquisition.
3. Standard subsetting by columns or rows match character vectors to the rownames or colnames, so any ExperimentList element with more than zero columns must have non-NULL colnames, and elements with more than zero rows must have non-NULL rownames.

Any data class that provides the following methods can be used as an element of ExperimentList. RangedSummarizedExperiment provides the template behavior for ExperimentList elements, as follows. These are "template" behavior, but not explicit requirements:

• colnames(), by returning a character vector of sample identifiers
• rownames(), by returning a character vector of feature identifiers, such as for genes, proteins, etc
• [i, j], by returning the restriction of the instance to rows i and columns j
• dim(), by returning integer vector of length two for the number of rows and columns

RangedRaggedAssay class

Overview

The RangedRaggedAssay class is an extension of the GRangesList Bioconductor class. It is intended to mainly handle segmented copy number data. The visual element of a RangedRaggedAssay class includes a ragged table where columns represent the samples and the rows disjoint ranges. This class allows for such operations as colnames and rownames. The assay acessor will return available experiment metadata columns.

Optional validity checks for developers

hasAssay function

The standard assay functionality allows the user to obtain a numeric matrix of data. The current hasAssay function includes a "soft" check that ensures all classes in an existing MultiAssayExperiment class object have listed assay methods via the hasMethods function. For convenience, the argument passed to the hasAssay function can either be a MultiAssayExperiment or a list class object.

Subset methods

Overview

A couple of methods for subsetting were created for the MultiAssayExperiment with a user-friendly interface in mind. Both the bracket notation [ and subset methods are available. Each allows for subsetting via numeric, character, and logical vectors. Additional support for list and List objects is available.

Bracket [ subsetting

Users are able to subset by:

• rows
• columns
• assays

respectively, within the bracket notation and seperated by commas ,. When subsetting a MultiAssayExperiment via a numeric vector, all rows and columns of each element in the ExperimentList will be subset by that vector. assays will be subset appropriately. When using a character vector, consideration is taken when subsetting a RangedRaggedAssay class by rownames. The characters in the vector will be matched against the rownames of the RangedRaggedAssay as with all other ExperimentList elements. The equivalent operation is performed for colnames and assays of the MultiAssayExperiment. Logical vectors will be passed to all dimensions of the MultiAssayExperiment (i.e., rows, columns, assays) and recycled as necessary. Subsetting with objects of class list or List decendants will be allowed only if the length of such list is the same as that of the number of experiments in the ExperimentList. The order of such lists is not checked and it is up to the user to ensure that the ordering is the same as that of the MultiAssayExperiment. Subsetting with lists and List decendants is only available for rows and columns.

drop argument

The drop argument indicates whether to keep assays with zero dimensions (after subsetting) in the ExperimentList class object.

Use of GRanges object to subset

In the instance where the user needs to find overlaps between objects containing genomic ranges (i.e., RangedRaggedAssay), the user may introduce a GRanges class object to make use of the findOverlaps functionality for subsetting. Additional arguments may be passed on to either the subset function or inside the bracket [ notation. See ?getHits for more details.

Experimental approach to model and plot specifications

Given a MultiAssayExperiment instance with elements named 'a', 'b', we propose that formulae can refer to the element names to select assays. The allLM_pw function operates on four basic inputs: a formula, a MultiAssayExperiment instance, and two optional transformation functions. mylms = allLM_pw(a~b, mae) will compute all pairwise regressions of features in element a of mae on features in element b of mae. The result is a list with two components: the list of all lm() fits, and a list of t-statistics for slopes.

pwplot(a~b, f1~f2, mae) will obtain feature f1 from element a of mae and f2 from element b of mae and form the scatterplot of feature values across all samples common to the two assays.

Coming: MultiAssayView class

This is not yet part of the official API, but is here as a placeholder.

Overview

The MultiAssayView class represents an initial step in the subsetting operations of the MultiAssayExperiment object. The main purpose of this class is to provide an explicit mechanism for intended and sequential subsetting operations without having to manipulate the full MultiAssayExperiment object in memory.

Structure

• query - Either a character or range-based class
• keeps - A list representation of matched queries for each assay in the MultiAssayExperiment
• drops - A list representation of unmatched queries to be dropped from the MultiAssayExperiment object
• type - An atomic character vector indicating the type of subset to be performed

Revision

• colnames
• rownames
• assay