SparseSummarizedExperiment-class: SparseSummarizedExperiment objects

In PeteHaitch/SparseSummarizedExperiment: SparseSummarizedExperiment Container

Description

The SparseSummarizedExperiment class extends the SummarizedExperiment class by adding the sparseAssays slot, which contains a SparseAssays object.

Note that SummarizedExperiment is the parent of the SparseSummarizedExperiment class which means that all methods documented in ?SummarizedExperiment also work on a SparseSummarizedExperiment. Note also that SparseSummarizedExperiment is a parent of the RangedSparseSummarizedExperiment class which means that all the methods documented below also work on a RangedSparseSummarizedExperiment. See ‘Implementation and Extension’ for details.

Usage

## Constructor

# See ?RangedSparseSummarizedExperiment for the constructor function.

## Accessors

sparseAssayNames(x, ...)
sparseAssayNames(x, ...) <- value
sparseAssays(x, ..., withDimnames = TRUE)
sparseAssays(x, ..., withDimnames = TRUE) <- value
sparseAssay(x, i, ...)
sparseAssay(x, i, ...) <- value

## Subsetting

## S4 method for signature 'SparseSummarizedExperiment'
x[i, j, ...]

## Combining

## S4 method for signature 
## 'SparseSummarizedExperiment,SparseSummarizedExperiment'
combine(x, y, ...)

Arguments

x, y	A SparseSummarizedExperiment object.
...	For sparseAssay, ... may contain withDimnames, which is forwarded to sparseAssays. For cbind, rbind, and combine, ... contains SparseSummarizedExperiment objects to be combined. For other accessors, ignored.
i, j	For sparseAssay, sparseAssay<-, i is a numeric or character scalar; see ‘Accessors’ for additional constraints. For [,SparseSummarizedExperiment, [,SparseSummarizedExperiment<-, i, j are subscripts that can act to subset the rows (features) and columns (samples) of x, that is the sparse assay elements of sparseAssays and the matrix elements of assays. For [[,SparseSummarizedExperiment, [[,SparseSummarizedExperiment<-, i, is a scalar index (e.g., character(1) or integer(1)) into a column of colData.
withDimnames	A logical(1), indicating whether dimnames should be applied to extracted sparse assay elements. Setting withDimnames = FALSE increases the speed and memory efficient with which sparse assays are extracted. withDimnames = TRUE in the setter sparseAssays<- allows efficient complex assignments (e.g., updating names of sparse assays, names(sparseAssays(x, withDimnames = FALSE)) <- ... is more efficient that names(sparseAssays(x)) <- ...); it does not influence actual assignment of dimnames to sparse assays. NOTE: For this particular example, it is simpler and just as efficient to use sparseAssayNames(x) <- ....
value	An object of a class specified in the S4 method signature or as outlined in ‘Details’.

Details

These details assume familiarity with the SummarizedExperiment class; please first read this linked documentation.

The SparseSummarizedExperiment class is meant for sparse numeric data derived from a sequencing experiment. These data are stored as a SparseAssays object in the sparseAssays slot of the SparseSummarizedExperiment. In this instance, sparse means data where there are multiple measurements per-feature, per-sample and where measurements with the same value (including missing values) are frequently observed. NOTE: SparseSummarizedExperiment objects only payoff compared to SummarizedExperiment when this condition is satisfied.

A SparseSummarizedExperiment object can also store non-sparse data by storing these data in the assays slot, as would be done in a SummarizedExperiment object.

The sparse data are accessed by using the sparseAssays funcion, described below. This returns a SimpleList object.

For an example of where SparseSummarizedExperiment objects are useful, please see the MethPat class in the MethylationTuples package (currently GitHub-only, https://github.com/PeteHaitch/MethylationTuples/).

Constructor

SparseSummarizedExperiment instances are constructed using the SparseSummarizedExperiment function documented in ?RangedSparseSummarizedExperiment.

Accessors

All the accessors documented in ?SummarizedExperiment are also applicable to SparseSummarizedExperiment objects. In addition, when x is a SparseSummarizedExperiment objects, the following accessors are applicable.

# TODO: Check equivalence claim

sparseAssays(x), sparseAssays(x) <- value:

Get or set the sparse assays. Unlike assays(x), sparseAssays(x) does not coerce the returned object to a SimpleList object but preserves it as the concrete SparseAssays subclass. value is a SparseAssays object with the same dimensions as x or a SimpleList object (which will be coerced to a SparseAssays object and must then have the same dimensions as x).

# TODO: Check equivalence claim # TODO: Could/should I allow value to be a SimpleList

sparseAssay(x, i), sparseAssay(x, i) <- value:

Get or set the ith (default first) sparse assay elements. Unlike assay(x, i), sparseAssay(x, i) allows vector i and preserves the returned object as the concrete SparseAssays subclass. value must be a SparseAssays object (with the same concrete subclass) of the same dimension as x, and with dimension names NULL or consistent with those of x and length equal to length(i).

sparseAssayNames(x), sparseAssayNames(x) <- value:

Get or set the names of sparseAssays() elements.

Subsetting

Subsetting behaviour is inherited from methods defined for SummarizedExperiment methods; see ?SummarizedExperiment.

Combining

SparseSummarizedExperiment objects can be combined in three different ways.

1. rbind Suitable for when each object has the same samples.

2. cbind Suitable for when each object has unique samples.

3. combine Suitable in either case, however, requires that dimnames are set on each object and that all objects have an identical number of sparse assays with identical names.

cbind() and rbind() behaviour is inherited from methods defined for SummarizedExperiment methods; see ?SummarizedExperiment. The sparseAssays slot is appropriately handled in a cbind() or rbind(); see cbind,SimpleListSparseAssays-method and rbind,SimpleListSparseAssays-method for details. Additionally, the SparseSummarizedExperiment defines combine methods for both SummarizedExperiment and SparseSummarizedExperiment objects. The sparseAssays slot is appropriately handled in a combine(); see combine,SimpleListSparseAssays,SimpleListSparseAssays-method for details.

Coercion

Coercion from a SparseSummarizedExperiment (resp. RangedSparseSummarizedExperiment) to a SummarizedExperiment (resp. RangedSummarizedExperiment) can be done in one of two ways. The first method uses implicit coercion, e.g., if x is a SparseSummarizedExperiment object then as(x, "SparseSummarizedExperiment") coerces it to a SummarizedExperiment but drops the sparseAssays slot. The second method uses an explicit coercion to coerce the SparseAssays object in sparseAssays slot into a Assays object and adds it to the assays slot of the resulting object, makeSEFromSSE(x).

Implementation and Extension

This section contains advanced material meant for package developers.

The SparseSummarizedExperiment/RangedSparseSummarizedExperiment class hierarchy is as follows:

SummarizedExperiment
|-- RangedSummarizedExperiment
|   |-- RangedSparseSummarizedExperiment
|-- SparseSummarizedExperiment
|   |-- RangedSparseSummarizedExperiment

That is, the RangedSparseSummarizedExperiment is a subclass of both SparseSummarizedExperiment and RangedSummarizedExperiment, although SparseSummarizedExperiment takes precedence.

SparseSummarizedExperiment is implemented as an S4 class, and can be extended in the usual way, using contains = "SparseSummarizedExperiment" in the new class definition. Similarly, the RangedSparseSummarizedExperiment can be extended using contains = "RangedSparseSummarizedExperiment" in the new class definition.

In addition, the representation of the sparseAssays slot of SparseSummarizedExperiment is as a virtual class, SparseAssays. This allows derived classes (contains = "SparseAssays") to easily implement alternative requirement for the sparse assays, e.g., backed by file-based storage like NetCDF or the ff package, while re-using the existing SparseSummarizedExperiment class without modification. See SparseAssays for more information.

The current sparseAssays slot is implemented as a SimpleListSparseAssays object.

It is generally advisable to work with the sparse representation of the data wherever possible, but there are times when the densified version of the sparse data are required. This can be achieved using the densify = TRUE argument in sparseAssays() and sparseAssay(). Note, however, that it is generally unadvisable to simultaneously densify all sparse assays and samples; see densify.

Author(s)

Peter Hickey, [e-mail]

See Also

• RangedSparseSummarizedExperiment objects.

• SummarizedExperiment objects in the SummarizedExperiment package.

• SparseAssays and SimpleListSparseAssays objects.

Examples

sl1 <- SimpleList(
s1 = SimpleList(key = as.integer(c(NA, 1, NA, NA, 2, NA, 3, NA, 4, 5)),
                value = matrix(1:10, ncol = 2)),
s2 = SimpleList(key = as.integer(c(NA, NA, 1, 2, NA, NA, 3, 4, NA, NA)),
                value = matrix(8:1, ncol = 2)))

sl2 <- SimpleList(
  s1 = SimpleList(key = as.integer(c(NA, 1, NA, 2, 2, NA, 1, NA, NA, 1)),
                  value = matrix(1:2, ncol = 1)),
  s2 = SimpleList(key = as.integer(c(1, 1, 1, 2, NA, NA, NA, NA, NA, NA)),
                  value = matrix(4:3, ncol = 1)))
sa <- SparseAssays(SimpleList(sa1 = sl1, sa2 = sl2))

colData <- DataFrame(Genotype = c("WT", "KO"),
                     row.names = c("s1", "s2"))
sse <- SparseSummarizedExperiment(sparseAssays = sa,
                                  colData = colData)
sse
dim(sse)
dimnames(sse)
sparseAssay(sse)
# densify the first sparse assay.
# In general its a bad idea to use densify = TRUE, but these data are small
# enough not to worry.
# TODO: Should I use sparseAssay() or sparseAssays() in the example; check
#       out SummarizedExperiment examples.
densify(sparseAssay(sse), 1, 1:2)[[1]]
SAapply(sparseAssays(sse), function(x) x^2)
## Not run: 
 # Need sparsify = TRUE to use the replace method
 sparseAssays(sse) <- SAapply(sparseAssays(sse), function(x) x^2)

## End(Not run)
sparseAssays(sse) <- SAapply(sparseAssays(sse), function(x) x^2,
                             sparsify = TRUE)
densify(sparseAssays(sse), 1:2, 1:2)

sparseAssay(sse)
# densify the first sparse assay
densify(sparseAssay(sse), 1, 1:2)[[1]]

sse[, sse$Genotype == "WT"]

## cbind() combines objects with the same features of interest
## but different samples:
sse1 <- sse
sse2 <- sse1[, 1]
colnames(sse2) <- "s3"
cmb1 <- cbind(sse1, sse2)
dim(cmb1)
dimnames(cmb1)

## rbind() combines objects with the same samples but different
## features of interest:
sse1 <- sse
sse2 <- sse1[1:5, ]
rownames(sse2) <- letters[1:nrow(sse2)]
cmb2 <- rbind(sse1, sse2)
dim(cmb2)
dimnames(cmb2)

## combine() combines objects with potentially different features of interest
## and different samples, by matching on names:
sse1 <- sse[1:5, ]
names(sse1) <- letters[1:5]
sse2 <- sse[3:8, 2]
names(sse2) <- letters[3:8]
cmb3 <- combine(sse1, sse2)
dim(cmb3)
dimnames(cmb3)

PeteHaitch/SparseSummarizedExperiment documentation built on May 8, 2019, 1:31 a.m.