altExps: Alternative Experiment methods

In SingleCellExperiment: S4 Classes for Single Cell Data

Description

In some experiments, different features must be normalized differently or have different row-level metadata. Typical examples would be for spike-in transcripts in plate-based experiments and antibody or CRISPR tags in CITE-seq experiments. These data cannot be stored in the main assays of the SingleCellExperiment itself. However, it is still desirable to store these features somewhere in the SingleCellExperiment. This simplifies book-keeping in long workflows and ensure that samples remain synchronised.

To facilitate this, the SingleCellExperiment class allows for “alternative Experiments”. Nested SummarizedExperiment-class objects are stored inside the SingleCellExperiment object x, in a manner that guarantees that the nested objects have the same columns in the same order as those in x. Methods are provided to enable convenient access to and manipulation of these alternative Experiments. Each alternative Experiment should contain experimental data and row metadata for a distinct set of features.

Getters

In the following examples, x is a SingleCellExperiment object.

altExp(x, e, withColData=FALSE):

Retrieves a SummarizedExperiment containing alternative features (rows) for all cells (columns) in x. e is either a string specifying the name of the alternative Experiment in x to retrieve, or a numeric scalar specifying the index of the desired Experiment. If withColData=TRUE, the column metadata of the output object is set to colData(x).

altExpNames(x):

Returns a character vector containing the names of all alternative Experiments in x. This is guaranteed to be of the same length as the number of results, though the names may not be unique.

altExps(x, withColData=FALSE):

Returns a named List of matrices containing one or more SummarizedExperiment objects. Each object has the same number of columns. If withColData=TRUE, the column metadata of each output object is set to colData(x).

Single-object setter

altExp(x, e) <- value will add or replace an alternative Experiment in a SingleCellExperiment object x. The value of e determines how the result is added or replaced:

• If e is missing, value is assigned to the first result. If the result already exists, its name is preserved; otherwise it is given a default name "unnamed1".

• If e is a numeric scalar, it must be within the range of existing results, and value will be assigned to the result at that index.

• If e is a string and a result exists with this name, value is assigned to to that result. Otherwise a new result with this name is append to the existing list of results.

value is expected to be a SummarizedExperiment object with number of columns equal to ncol(x). Alternatively, if value is NULL, the alternative Experiment at e is removed from the object.

Other setters

In the following examples, x is a SingleCellExperiment object.

altExps(x) <- value:

Replaces all alterrnative Experiments in x with those in value. The latter should be a list-like object containing any number of SummarizedExperiment objects with number of columns equal to ncol(x).

If value is named, those names will be used to name the alternative Experiments in x. Otherwise, unnamed results are assigned default names prefixed with "unnamed".

If value is NULL, all alternative Experiments in x are removed.

altExpNames(x) <- value:

Replaces all names for alternative Experiments in x with a character vector value. This should be of length equal to the number of results currently in x.

removeAltExps(x) will remove all alternative Experiments from x. This has the same effect as altExps(x) <- NULL but may be more convenient as it directly returns a SingleCellExperiment.

Author(s)

Aaron Lun

See Also

splitAltExps, for a convenient way of adding alternative Experiments from existing features.

swapAltExp, to swap the main and alternative Experiments.

Examples

example(SingleCellExperiment, echo=FALSE) # Using the class example
dim(counts(sce))

# Mocking up some alternative Experiments.
se1 <- SummarizedExperiment(matrix(rpois(1000, 5), ncol=ncol(se)))
rowData(se1)$stuff <- sample(LETTERS, nrow(se1), replace=TRUE)
se2 <- SummarizedExperiment(matrix(rpois(500, 5), ncol=ncol(se)))
rowData(se2)$blah <- sample(letters, nrow(se2), replace=TRUE)

# Setting the alternative Experiments.
altExp(sce, "spike-in") <- se1
altExp(sce, "CRISPR") <- se2

# Getting alternative Experimental data.
altExpNames(sce)
altExp(sce, "spike-in")
altExp(sce, 2)

# Setting alternative Experimental data.
altExpNames(sce) <- c("ERCC", "Ab")
altExp(sce, "ERCC") <- se1[1:2,]

SingleCellExperiment documentation built on Nov. 8, 2020, 7:51 p.m.