MultiAssayExperiment - An integrative multi-assay class for experiment data
Source:R/MultiAssayExperiment-class.R
, R/MultiAssayExperiment-methods.R
, R/assay-methods.R
MultiAssayExperiment-class.Rd
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
.
Usage
# S4 method for class 'MultiAssayExperiment'
show(object)
# S4 method for class 'MultiAssayExperiment'
length(x)
# S4 method for class 'MultiAssayExperiment'
names(x)
# S4 method for class 'MultiAssayExperiment'
updateObject(object, ..., verbose = FALSE)
# S4 method for class 'MultiAssayExperiment'
dimnames(x)
# S4 method for class 'MultiAssayExperiment'
c(x, ..., sampleMap = NULL, mapFrom = NULL)
# S4 method for class 'MultiAssayExperiment'
exportClass(
object,
dir = tempdir(),
fmt,
ext,
match = FALSE,
verbose = TRUE,
...
)
# S4 method for class 'MultiAssayExperiment'
assays(x, withDimnames = TRUE, ...)
# S4 method for class 'MultiAssayExperiment,missing'
assay(x, i, withDimnames = TRUE, ...)
# S4 method for class 'MultiAssayExperiment,numeric'
assay(x, i, withDimnames = TRUE, ...)
# S4 method for class '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: asampleMap
list
orDataFrame
to guide merge- mapFrom
Either a
logical
,character
, orinteger
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 bywrite.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
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 argumentassay: may contain withDimnames, which is forwarded to assays
combining c: compatible
MultiAssayExperiment
classes passed on to theExperimentList
constructor, can be alist
,List
, or a series of named arguments. See the examples below.
Methods (by generic)
show(MultiAssayExperiment)
: Show method for aMultiAssayExperiment
length(MultiAssayExperiment)
: Get the length of ExperimentListnames(MultiAssayExperiment)
: Get the names of the ExperimentListupdateObject(MultiAssayExperiment)
: Update old serialized MultiAssayExperiment objects to new APIdimnames(MultiAssayExperiment)
: Get the dimension names for aMultiAssayExperiment
objectc(MultiAssayExperiment)
: Add a supported data class to theExperimentList
exportClass(MultiAssayExperiment)
: Export data from class to a series of text filesassays(MultiAssayExperiment)
: Obtain aSimpleList
of assay data for all available experiments in the objectassay(x = MultiAssayExperiment, i = missing)
: Convenience function for extracting the assay of the first element (default) in theExperimentList
. Anumeric
orcharacter
index can also be provided
Slots
ExperimentList
A
ExperimentList
class object for each assay datasetcolData
A
DataFrame
of all clinical/specimen data available across experimentssampleMap
A
DataFrame
of translatable identifiers of samples and participantsmetadata
Additional data describing the
MultiAssayExperiment
objectdrops
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
methods::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
methods::as function.
In the following example, x
is a MultiAssayExperiment
:
MultiAssayExperimentToMAF(x)
See also
MultiAssayExperiment-methods for slot modifying methods, MultiAssayExperiment API
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 'drops()'
#> 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