altExps: Alternative Experiment methods
In drisso/SingleCellExperiment: S4 Classes for Single Cell Data

altExps

R Documentation

Alternative Experiment methods

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, withDimnames=TRUE, withColData=FALSE):

Retrieves a SummarizedExperiment containing alternative features (rows) for all cells (columns) in x. e should either be a string specifying the name of the alternative Experiment in x to retrieve, or a numeric scalar specifying the index of the desired Experiment, defaulting to the first Experiment is missing.

If withDimnames=TRUE, the column names of the output object are set to colnames(x). In addition, if withColData=TRUE, colData(x) is cbinded to the front of the column data of the output object.

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, withDimnames=TRUE, withColData=FALSE):

Returns a named List of matrices containing one or more SummarizedExperiment objects. Each object is guaranteed to have the same number of columns, in a 1:1 correspondence to those in x.

If withDimnames=TRUE, the column names of each output object are set to colnames(x). In addition, if withColData=TRUE, colData(x) is cbinded to the front of the column data of each output object.

Single-object setter

altExp(x, e, withDimnames=TRUE, withColData=FALSE) <- 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.

If withDimnames=TRUE, the column names of value are checked against those of x. A warning is raised if these are not identical, with the only exception being when value=NULL. This is inspired by the argument of the same name in assay<-.

If withColData=TRUE, we assume that the left-most columns of colData(value) are identical to colData(x). If so, these columns are removed, effectively reversing the withColData=TRUE setting for the altExp getter. Otherwise, a warning is raised.

Other setters

In the following examples, x is a SingleCellExperiment object.

altExps(x, withDimnames=TRUE, withColData=FALSE) <- 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.

If value is a Annotated object, any metadata will be retained in altExps(x). If value is a Vector object, any mcols will also be retained.

If withDimnames=TRUE, the column names of each entry of value are checked against those of x. A warning is raised if these are not identical.

If withColData=TRUE, we assume that the left-most columns of the colData for each entry of value are identical to colData(x). If so, these columns are removed, effectively reversing the withColData=TRUE setting for the altExps getter. Otherwise, a warning is raised.

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.

Main Experiment naming

The alternative Experiments are naturally associated with names (e during assignment). However, we can also name the main Experiment in a SingleCellExperiment x:

mainExpName(x) <- value:: Set the name of the main Experiment to a non-NA string value. This can also be used to unset the name if value=NULL.
mainExpName(x):: Returns a string containing the name of the main Experiment. This may also be NULL if no name is specified.

The presence of a non-NULL main Experiment name is helpful for functions like swapAltExp. An appropriate name is automatically added by functions like splitAltExps.

Note that, if a SingleCellExperiment is assigned as an alternative Experiment to another SingleCellExperiment via altExp(x, e) <- value, no attempt is made to synchronize mainExpName(value) with e. In such cases, we suggest setting mainExpName(value) to NULL to avoid any confusion during interpretation.

Author(s)

Aaron Lun

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,]

drisso/SingleCellExperiment documentation built on March 28, 2024, 7:49 a.m.