MultiAssayExperiment - An integrative multi-assay class for experiment data — MultiAssayExperiment-class • MultiAssayExperiment

The MultiAssayExperiment class can be used to manage results of diverse assays on a collection of specimen. Currently, the class can handle assays that are organized instances of SummarizedExperiment, ExpressionSet, matrix, RaggedExperiment (inherits from GRangesList), and RangedVcfStack. Create new MultiAssayExperiment instances with the homonymous constructor, minimally with the argument ExperimentList, potentially also with the arguments colData (see section below) and sampleMap.

# S4 method for MultiAssayExperiment
show(object)

# S4 method for MultiAssayExperiment
length(x)

# S4 method for MultiAssayExperiment
names(x)

# S4 method for MultiAssayExperiment
updateObject(object, ..., verbose = FALSE)

# S4 method for MultiAssayExperiment
dimnames(x)

# S4 method for MultiAssayExperiment
c(x, ..., sampleMap = NULL, mapFrom = NULL)

# S4 method for MultiAssayExperiment
exportClass(
  object,
  dir = tempdir(),
  fmt,
  ext,
  match = FALSE,
  verbose = TRUE,
  ...
)

# S4 method for MultiAssayExperiment
assays(x, withDimnames = TRUE, ...)

# S4 method for MultiAssayExperiment,missing
assay(x, i, withDimnames = TRUE, ...)

# S4 method for MultiAssayExperiment,numeric
assay(x, i, withDimnames = TRUE, ...)

# S4 method for MultiAssayExperiment,character
assay(x, i, withDimnames = TRUE, ...)

Arguments

object, x: A MultiAssayExperiment object
...: Additional arguments for supporting functions. See details.
verbose: logical(1) Whether to print additional information (default TRUE)
sampleMap: c method: a sampleMap list or DataFrame to guide merge
mapFrom: Either a logical, character, or integer vector indicating the experiment(s) that have an identical colname order as the experiment input(s). If using a character input, the name must match exactly.
dir: character(1) A directory for saving exported data (default: `tempdir()`)
fmt: character(1) or function() Either a format character atomic as supported by `write.table` either ('csv', or 'tsv') or a function whose first two arguments are 'object to save' and 'file location'
ext: character(1) A file extension supported by the format argument
match: logical(1) Whether to coerce the current object to a 'MatchedAssayExperiment' object (default: FALSE)
withDimnames: logical (default TRUE) whether to return dimension names included in the object
i: An integer or character scalar indicating the assay to return

Value

A MultiAssayExperiment object

Details

The dots (...) argument allows the user to specify additional arguments in several instances.

subsetting [: additional arguments sent to findOverlaps.
mergeReplicates: used to specify arguments for the simplify functional argument
assay: may contain withDimnames, which is forwarded to assays
combining c: compatible MultiAssayExperiment classes passed on to the ExperimentList constructor, can be a list, List, or a series of named arguments. See the examples below.

Methods (by generic)

show(MultiAssayExperiment): Show method for a MultiAssayExperiment
length(MultiAssayExperiment): Get the length of ExperimentList
names(MultiAssayExperiment): Get the names of the ExperimentList
updateObject(MultiAssayExperiment): Update old serialized MultiAssayExperiment objects to new API
dimnames(MultiAssayExperiment): Get the dimension names for a MultiAssayExperiment object
c(MultiAssayExperiment): Add a supported data class to the ExperimentList
exportClass(MultiAssayExperiment): Export data from class to a series of text files
assays(MultiAssayExperiment): Obtain a SimpleList of assay data for all available experiments in the object
assay(x = MultiAssayExperiment, i = missing): Convenience function for extracting the assay of the first element (default) in the ExperimentList. A numeric or character index can also be provided

Slots

ExperimentList: A ExperimentList class object for each assay dataset
colData: A DataFrame of all clinical/specimen data available across experiments
sampleMap: A DataFrame of translatable identifiers of samples and participants
metadata: Additional data describing the MultiAssayExperiment object
drops: A metadata list of dropped information

colData

The colData slot is a collection of primary specimen data valid across all experiments. This slot is strictly of class DataFrame but arguments for the constructor function allow arguments to be of class data.frame and subsequently coerced.

ExperimentList

The ExperimentList slot is designed to contain results from each experiment/assay. It contains a SimpleList.

sampleMap

The sampleMap contains a DataFrame of translatable identifiers of samples and participants or biological units. The standard column names of the sampleMap are "assay", "primary", and "colname". Note that the "assay" column is a factor corresponding to the names of each experiment in the ExperimentList. In the case where these names do not match between the sampleMap and the experiments, the documented experiments in the sampleMap take precedence and experiments are dropped by the harmonization procedure. The constructor function will generate a sampleMap in the case where it is not provided and this method may be a 'safer' alternative for creating the MultiAssayExperiment (so long as the rownames are identical in the colData, if provided). An empty sampleMap may produce empty experiments if the levels of the "assay" factor in the sampleMap do not match the names in the ExperimentList.

coercion

Convert a list or S4 List to a MultiAssayExperiment object using the as function.

In the following example, x is either a list or List:

as(x, "MultiAssayExperiment")

Convert a MultiAssayExperiment to MAF class object using the as function.

In the following example, x is a MultiAssayExperiment:

MultiAssayExperimentToMAF(x)

Examples

example("MultiAssayExperiment")
#> 
#> MltAsE> ## Run the example ExperimentList
#> MltAsE> example("ExperimentList")
#> 
#> ExprmL> ## Create an empty ExperimentList instance
#> ExprmL> ExperimentList()
#> ExperimentList class object of length 0:
#>  
#> ExprmL> ## Create array matrix and AnnotatedDataFrame to create an ExpressionSet class
#> ExprmL> arraydat <- matrix(data = seq(101, length.out = 20), ncol = 4,
#> ExprmL+     dimnames = list(
#> ExprmL+         c("ENST00000294241", "ENST00000355076",
#> ExprmL+         "ENST00000383706","ENST00000234812", "ENST00000383323"),
#> ExprmL+         c("array1", "array2", "array3", "array4")
#> ExprmL+     ))
#> 
#> ExprmL> colDat <- data.frame(slope53 = rnorm(4),
#> ExprmL+     row.names = c("array1", "array2", "array3", "array4"))
#> 
#> ExprmL> ## SummarizedExperiment constructor
#> ExprmL> exprdat <- SummarizedExperiment::SummarizedExperiment(arraydat,
#> ExprmL+     colData = colDat)
#> 
#> ExprmL> ## Create a sample methylation dataset
#> ExprmL> methyldat <- matrix(data = seq(1, length.out = 25), ncol = 5,
#> ExprmL+     dimnames = list(
#> ExprmL+         c("ENST00000355076", "ENST00000383706",
#> ExprmL+           "ENST00000383323", "ENST00000234812", "ENST00000294241"),
#> ExprmL+         c("methyl1", "methyl2", "methyl3",
#> ExprmL+           "methyl4", "methyl5")
#> ExprmL+     ))
#> 
#> ExprmL> ## Create a sample RNASeqGene dataset
#> ExprmL> rnadat <- matrix(
#> ExprmL+     data = sample(c(46851, 5, 19, 13, 2197, 507,
#> ExprmL+         84318, 126, 17, 21, 23979, 614), size = 20, replace = TRUE),
#> ExprmL+     ncol = 4,
#> ExprmL+     dimnames = list(
#> ExprmL+         c("XIST", "RPS4Y1", "KDM5D", "ENST00000383323", "ENST00000234812"),
#> ExprmL+         c("samparray1", "samparray2", "samparray3", "samparray4")
#> ExprmL+     ))
#> 
#> ExprmL> ## Create a mock RangedSummarizedExperiment from a data.frame
#> ExprmL> rangedat <- data.frame(chr="chr2", start = 11:15, end = 12:16,
#> ExprmL+     strand = c("+", "-", "+", "*", "."),
#> ExprmL+     samp0 = c(0,0,1,1,1), samp1 = c(1,0,1,0,1), samp2 = c(0,1,0,1,0),
#> ExprmL+     row.names = c(paste0("ENST", "00000", 135411:135414), "ENST00000383323"))
#> 
#> ExprmL> rangeSE <- SummarizedExperiment::makeSummarizedExperimentFromDataFrame(rangedat)
#> 
#> ExprmL> ## Combine to a named list and call the ExperimentList constructor function
#> ExprmL> assayList <- list(Affy = exprdat, Methyl450k = methyldat, RNASeqGene = rnadat,
#> ExprmL+                 GISTIC = rangeSE)
#> 
#> ExprmL> ## Use the ExperimentList constructor
#> ExprmL> ExpList <- ExperimentList(assayList)
#> 
#> MltAsE> ## Create sample maps for each experiment
#> MltAsE> exprmap <- data.frame(
#> MltAsE+     primary = c("Jack", "Jill", "Barbara", "Bob"),
#> MltAsE+     colname = c("array1", "array2", "array3", "array4"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> methylmap <- data.frame(
#> MltAsE+     primary = c("Jack", "Jack", "Jill", "Barbara", "Bob"),
#> MltAsE+     colname = c("methyl1", "methyl2", "methyl3", "methyl4", "methyl5"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> rnamap <- data.frame(
#> MltAsE+     primary = c("Jack", "Jill", "Bob", "Barbara"),
#> MltAsE+     colname = c("samparray1", "samparray2", "samparray3", "samparray4"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> gistmap <- data.frame(
#> MltAsE+     primary = c("Jack", "Bob", "Jill"),
#> MltAsE+     colname = c("samp0", "samp1", "samp2"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> ## Combine as a named list and convert to a DataFrame
#> MltAsE> maplist <- list(Affy = exprmap, Methyl450k = methylmap,
#> MltAsE+     RNASeqGene = rnamap, GISTIC = gistmap)
#> 
#> MltAsE> ## Create a sampleMap
#> MltAsE> sampMap <- listToMap(maplist)
#> 
#> MltAsE> ## Create an example phenotype data
#> MltAsE> colDat <- data.frame(sex = c("M", "F", "M", "F"), age = 38:41,
#> MltAsE+     row.names = c("Jack", "Jill", "Bob", "Barbara"))
#> 
#> MltAsE> ## Create a MultiAssayExperiment instance
#> MltAsE> mae <- MultiAssayExperiment(experiments = ExpList, colData = colDat,
#> MltAsE+     sampleMap = sampMap)

## Subsetting
# Rows (i) Rows/Features in each experiment
mae[1, , ]
#> A MultiAssayExperiment object of 4 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 4:
#>  [1] Affy: SummarizedExperiment with 1 rows and 4 columns
#>  [2] Methyl450k: matrix with 1 rows and 5 columns
#>  [3] RNASeqGene: matrix with 1 rows and 4 columns
#>  [4] GISTIC: RangedSummarizedExperiment with 1 rows and 3 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files
mae[c(TRUE, FALSE), , ]
#> A MultiAssayExperiment object of 4 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 4:
#>  [1] Affy: SummarizedExperiment with 3 rows and 4 columns
#>  [2] Methyl450k: matrix with 3 rows and 5 columns
#>  [3] RNASeqGene: matrix with 3 rows and 4 columns
#>  [4] GISTIC: RangedSummarizedExperiment with 3 rows and 3 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files

# Columns (j) Rows in colData
mae[, rownames(colData(mae))[3:2],  ]
#> A MultiAssayExperiment object of 4 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 4:
#>  [1] Affy: SummarizedExperiment with 5 rows and 2 columns
#>  [2] Methyl450k: matrix with 5 rows and 2 columns
#>  [3] RNASeqGene: matrix with 5 rows and 2 columns
#>  [4] GISTIC: RangedSummarizedExperiment with 5 rows and 2 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files

# Assays (k)
mae[, , "Affy"]
#> Warning: 'experiments' dropped; see 'metadata'
#> harmonizing input:
#>   removing 12 sampleMap rows not in names(experiments)
#> A MultiAssayExperiment object of 1 listed
#>  experiment with a user-defined name and respective class.
#>  Containing an ExperimentList class object of length 1:
#>  [1] Affy: SummarizedExperiment with 5 rows and 4 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files

## Complete cases (returns logical vector)
completes <- complete.cases(mae)
compMAE <- mae[, completes, ]
compMAE
#> A MultiAssayExperiment object of 4 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 4:
#>  [1] Affy: SummarizedExperiment with 5 rows and 3 columns
#>  [2] Methyl450k: matrix with 5 rows and 4 columns
#>  [3] RNASeqGene: matrix with 5 rows and 3 columns
#>  [4] GISTIC: RangedSummarizedExperiment with 5 rows and 3 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files
colData(compMAE)
#> DataFrame with 3 rows and 2 columns
#>              sex       age
#>      <character> <integer>
#> Jack           M        38
#> Jill           F        39
#> Bob            M        40

example("MultiAssayExperiment")
#> 
#> MltAsE> ## Run the example ExperimentList
#> MltAsE> example("ExperimentList")
#> 
#> ExprmL> ## Create an empty ExperimentList instance
#> ExprmL> ExperimentList()
#> ExperimentList class object of length 0:
#>  
#> ExprmL> ## Create array matrix and AnnotatedDataFrame to create an ExpressionSet class
#> ExprmL> arraydat <- matrix(data = seq(101, length.out = 20), ncol = 4,
#> ExprmL+     dimnames = list(
#> ExprmL+         c("ENST00000294241", "ENST00000355076",
#> ExprmL+         "ENST00000383706","ENST00000234812", "ENST00000383323"),
#> ExprmL+         c("array1", "array2", "array3", "array4")
#> ExprmL+     ))
#> 
#> ExprmL> colDat <- data.frame(slope53 = rnorm(4),
#> ExprmL+     row.names = c("array1", "array2", "array3", "array4"))
#> 
#> ExprmL> ## SummarizedExperiment constructor
#> ExprmL> exprdat <- SummarizedExperiment::SummarizedExperiment(arraydat,
#> ExprmL+     colData = colDat)
#> 
#> ExprmL> ## Create a sample methylation dataset
#> ExprmL> methyldat <- matrix(data = seq(1, length.out = 25), ncol = 5,
#> ExprmL+     dimnames = list(
#> ExprmL+         c("ENST00000355076", "ENST00000383706",
#> ExprmL+           "ENST00000383323", "ENST00000234812", "ENST00000294241"),
#> ExprmL+         c("methyl1", "methyl2", "methyl3",
#> ExprmL+           "methyl4", "methyl5")
#> ExprmL+     ))
#> 
#> ExprmL> ## Create a sample RNASeqGene dataset
#> ExprmL> rnadat <- matrix(
#> ExprmL+     data = sample(c(46851, 5, 19, 13, 2197, 507,
#> ExprmL+         84318, 126, 17, 21, 23979, 614), size = 20, replace = TRUE),
#> ExprmL+     ncol = 4,
#> ExprmL+     dimnames = list(
#> ExprmL+         c("XIST", "RPS4Y1", "KDM5D", "ENST00000383323", "ENST00000234812"),
#> ExprmL+         c("samparray1", "samparray2", "samparray3", "samparray4")
#> ExprmL+     ))
#> 
#> ExprmL> ## Create a mock RangedSummarizedExperiment from a data.frame
#> ExprmL> rangedat <- data.frame(chr="chr2", start = 11:15, end = 12:16,
#> ExprmL+     strand = c("+", "-", "+", "*", "."),
#> ExprmL+     samp0 = c(0,0,1,1,1), samp1 = c(1,0,1,0,1), samp2 = c(0,1,0,1,0),
#> ExprmL+     row.names = c(paste0("ENST", "00000", 135411:135414), "ENST00000383323"))
#> 
#> ExprmL> rangeSE <- SummarizedExperiment::makeSummarizedExperimentFromDataFrame(rangedat)
#> 
#> ExprmL> ## Combine to a named list and call the ExperimentList constructor function
#> ExprmL> assayList <- list(Affy = exprdat, Methyl450k = methyldat, RNASeqGene = rnadat,
#> ExprmL+                 GISTIC = rangeSE)
#> 
#> ExprmL> ## Use the ExperimentList constructor
#> ExprmL> ExpList <- ExperimentList(assayList)
#> 
#> MltAsE> ## Create sample maps for each experiment
#> MltAsE> exprmap <- data.frame(
#> MltAsE+     primary = c("Jack", "Jill", "Barbara", "Bob"),
#> MltAsE+     colname = c("array1", "array2", "array3", "array4"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> methylmap <- data.frame(
#> MltAsE+     primary = c("Jack", "Jack", "Jill", "Barbara", "Bob"),
#> MltAsE+     colname = c("methyl1", "methyl2", "methyl3", "methyl4", "methyl5"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> rnamap <- data.frame(
#> MltAsE+     primary = c("Jack", "Jill", "Bob", "Barbara"),
#> MltAsE+     colname = c("samparray1", "samparray2", "samparray3", "samparray4"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> gistmap <- data.frame(
#> MltAsE+     primary = c("Jack", "Bob", "Jill"),
#> MltAsE+     colname = c("samp0", "samp1", "samp2"),
#> MltAsE+     stringsAsFactors = FALSE)
#> 
#> MltAsE> ## Combine as a named list and convert to a DataFrame
#> MltAsE> maplist <- list(Affy = exprmap, Methyl450k = methylmap,
#> MltAsE+     RNASeqGene = rnamap, GISTIC = gistmap)
#> 
#> MltAsE> ## Create a sampleMap
#> MltAsE> sampMap <- listToMap(maplist)
#> 
#> MltAsE> ## Create an example phenotype data
#> MltAsE> colDat <- data.frame(sex = c("M", "F", "M", "F"), age = 38:41,
#> MltAsE+     row.names = c("Jack", "Jill", "Bob", "Barbara"))
#> 
#> MltAsE> ## Create a MultiAssayExperiment instance
#> MltAsE> mae <- MultiAssayExperiment(experiments = ExpList, colData = colDat,
#> MltAsE+     sampleMap = sampMap)

## Add an experiment
test1 <- mae[[1L]]
colnames(test1) <- rownames(colData(mae))

## Combine current MultiAssayExperiment with additional experiment
## (no sampleMap)
c(mae, newExperiment = test1)
#> A MultiAssayExperiment object of 5 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 5:
#>  [1] Affy: SummarizedExperiment with 5 rows and 4 columns
#>  [2] Methyl450k: matrix with 5 rows and 5 columns
#>  [3] RNASeqGene: matrix with 5 rows and 4 columns
#>  [4] GISTIC: RangedSummarizedExperiment with 5 rows and 3 columns
#>  [5] newExperiment: SummarizedExperiment with 5 rows and 4 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files

test2 <- mae[[3L]]
c(mae, newExp = test2, mapFrom = 3L)
#> Warning: Assuming column order in the data provided 
#>  matches the order in 'mapFrom' experiment(s) colnames
#> A MultiAssayExperiment object of 5 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 5:
#>  [1] Affy: SummarizedExperiment with 5 rows and 4 columns
#>  [2] Methyl450k: matrix with 5 rows and 5 columns
#>  [3] RNASeqGene: matrix with 5 rows and 4 columns
#>  [4] GISTIC: RangedSummarizedExperiment with 5 rows and 3 columns
#>  [5] newExp: matrix with 5 rows and 4 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files

## Add experiment using experiment name in mapFrom
c(mae, RNASeqGeneV2 = test2, mapFrom = "RNASeqGene")
#> Warning: Assuming column order in the data provided 
#>  matches the order in 'mapFrom' experiment(s) colnames
#> A MultiAssayExperiment object of 5 listed
#>  experiments with user-defined names and respective classes.
#>  Containing an ExperimentList class object of length 5:
#>  [1] Affy: SummarizedExperiment with 5 rows and 4 columns
#>  [2] Methyl450k: matrix with 5 rows and 5 columns
#>  [3] RNASeqGene: matrix with 5 rows and 4 columns
#>  [4] GISTIC: RangedSummarizedExperiment with 5 rows and 3 columns
#>  [5] RNASeqGeneV2: matrix with 5 rows and 4 columns
#> Functionality:
#>  experiments() - obtain the ExperimentList instance
#>  colData() - the primary/phenotype DataFrame
#>  sampleMap() - the sample coordination DataFrame
#>  `$`, `[`, `[[` - extract colData columns, subset, or experiment
#>  *Format() - convert into a long or wide DataFrame
#>  assays() - convert ExperimentList to a SimpleList of matrices
#>  exportClass() - save data to flat files

MultiAssayExperiment - An integrative multi-assay class for experiment data