swapAltExp: Swap main and alternative Experiments

In LTLA/SingleCellExperiment: S4 Classes for Single Cell Data

Swap main and alternative Experiments

Description

Swap the main Experiment for an alternative Experiment in a SingleCellExperiment object.

Usage

swapAltExp(x, name, saved = mainExpName(x), withColData = TRUE)

Arguments

x	A SingleCellExperiment object.
name	String or integer scalar specifying the alternative Experiment to use to replace the main Experiment.
saved	String specifying the name to use to save the original x as an alternative experiment in the output. If NULL, the original is not saved.
withColData	Logical scalar specifying whether the column metadata of x should be preserved in the output.

Details

During the course of an analysis, we may need to perform operations on each of the alternative Experiments in turn. This would require us to repeatedly call altExp(x, name) prior to running downstream functions on those Experiments. In such cases, it may be more convenient to switch the main Experiment with the desired alternative Experiments, allowing a particular section of the analysis to be performed on the latter by default.

For example, the initial phases of the analysis might use the entire set of features. At some point, we might want to focus only on a subset of features of interest, but we do not want to discard the rest of the features. This can be achieved by storing the subset as an alternative Experiment and swapping it with the main Experiment, as shown in the Examples below.

If withColData=TRUE, the column metadata of the output object is set to colData(x). As a side-effect, any column data previously altExp(x, name) is stored in the saved alternative Experiment of the output. This is necessary to preserve the column metadata while achieving reversibility (see below). Setting withColData=FALSE will omit the colData exchange.

swapAltExp is almost perfectly reversible, i.e., swapAltExp(swapAltExp(x, name, saved), saved, name) should return something very similar to x. The only exceptions are that the order of altExpNames is changed, and that any non-NULL mainExpName in altExp(x, name) will be lost.

Value

A SingleCellExperiment derived from altExp(x, name). This contains all alternative Experiments in altExps(x), excluding the one that was promoted to the main Experiment. An additional alternative Experiment containing x may be included if saved is specified.

Author(s)

Aaron Lun

See Also

altExps, for a description of the alternative Experiment concept.

Examples

example(SingleCellExperiment, echo=FALSE) # using the class example

# Let's say we defined a subset of genes of interest.
# We can save the feature set as its own altExp.
hvgs <- 1:10
altExp(sce, "subset") <- sce[hvgs,] 

# At some point, we want to do our analysis on the HVGs only,
# but we want to hold onto the other features for later reference.
sce <- swapAltExp(sce, name="subset", saved="all")
sce

# Once we're done, it is straightforward to switch back.
swapAltExp(sce, "all") 

LTLA/SingleCellExperiment documentation built on Nov. 12, 2024, 6:58 a.m.