LTLA authored on 19/01/2021 02:54:06
| ... | ... |
@@ -4,7 +4,7 @@ |
| 4 | 4 |
\alias{swapAltExp}
|
| 5 | 5 |
\title{Swap main and alternative Experiments}
|
| 6 | 6 |
\usage{
|
| 7 |
-swapAltExp(x, name, saved = NULL, withColData = TRUE) |
|
| 7 |
+swapAltExp(x, name, saved = mainExpName(x), withColData = TRUE) |
|
| 8 | 8 |
} |
| 9 | 9 |
\arguments{
|
| 10 | 10 |
\item{x}{A \linkS4class{SingleCellExperiment} object.}
|
| ... | ... |
@@ -18,9 +18,8 @@ If \code{NULL}, the original is not saved.}
|
| 18 | 18 |
} |
| 19 | 19 |
\value{
|
| 20 | 20 |
A SingleCellExperiment derived from \code{altExp(x, name)}.
|
| 21 |
-This contains all alternative Experiments in \code{altExps(x)},
|
|
| 22 |
-with an additional entry containing \code{x} if \code{saved} is specified.
|
|
| 23 |
-If \code{withColData=TRUE}, the column metadata is set to \code{colData(x)}.
|
|
| 21 |
+This contains all alternative Experiments in \code{altExps(x)}, excluding the one that was promoted to the main Experiment.
|
|
| 22 |
+An additional alternative Experiment containing \code{x} may be included if \code{saved} is specified.
|
|
| 24 | 23 |
} |
| 25 | 24 |
\description{
|
| 26 | 25 |
Swap the main Experiment for an alternative Experiment in a \linkS4class{SingleCellExperiment} object.
|
| ... | ... |
@@ -36,6 +35,15 @@ At some point, we might want to focus only on a subset of features of interest, |
| 36 | 35 |
but we do not want to discard the rest of the features. |
| 37 | 36 |
This can be achieved by storing the subset as an alternative Experiment and swapping it with the main Experiment, |
| 38 | 37 |
as shown in the Examples below. |
| 38 |
+ |
|
| 39 |
+If \code{withColData=TRUE}, the column metadata of the output object is set to \code{colData(x)}.
|
|
| 40 |
+As a side-effect, any column data previously \code{altExp(x, name)} is stored in the \code{saved} alternative Experiment of the output.
|
|
| 41 |
+This is necessary to preserve the column metadata while achieving reversibility (see below). |
|
| 42 |
+Setting \code{withColData=FALSE} will omit the \code{colData} exchange.
|
|
| 43 |
+ |
|
| 44 |
+\code{swapAltExp} is almost perfectly reversible, i.e., \code{swapAltExp(swapAltExp(x, name, saved), saved, name)} should return something very similar to \code{x}.
|
|
| 45 |
+The only exceptions are that the order of \code{\link{altExpNames}} is changed,
|
|
| 46 |
+and that any non-\code{NULL} \code{\link{mainExpName}} in \code{altExp(x, name)} will be lost.
|
|
| 39 | 47 |
} |
| 40 | 48 |
\examples{
|
| 41 | 49 |
example(SingleCellExperiment, echo=FALSE) # using the class example |
LTLA authored on 29/09/2019 05:07:40
| 1 | 1 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,61 @@ |
| 1 |
+% Generated by roxygen2: do not edit by hand |
|
| 2 |
+% Please edit documentation in R/swapAltExp.R |
|
| 3 |
+\name{swapAltExp}
|
|
| 4 |
+\alias{swapAltExp}
|
|
| 5 |
+\title{Swap main and alternative Experiments}
|
|
| 6 |
+\usage{
|
|
| 7 |
+swapAltExp(x, name, saved = NULL, withColData = TRUE) |
|
| 8 |
+} |
|
| 9 |
+\arguments{
|
|
| 10 |
+\item{x}{A \linkS4class{SingleCellExperiment} object.}
|
|
| 11 |
+ |
|
| 12 |
+\item{name}{String or integer scalar specifying the alternative Experiment to use to replace the main Experiment.}
|
|
| 13 |
+ |
|
| 14 |
+\item{saved}{String specifying the name to use to save the original \code{x} as an alternative experiment in the output.
|
|
| 15 |
+If \code{NULL}, the original is not saved.}
|
|
| 16 |
+ |
|
| 17 |
+\item{withColData}{Logical scalar specifying whether the column metadata of \code{x} should be preserved in the output.}
|
|
| 18 |
+} |
|
| 19 |
+\value{
|
|
| 20 |
+A SingleCellExperiment derived from \code{altExp(x, name)}.
|
|
| 21 |
+This contains all alternative Experiments in \code{altExps(x)},
|
|
| 22 |
+with an additional entry containing \code{x} if \code{saved} is specified.
|
|
| 23 |
+If \code{withColData=TRUE}, the column metadata is set to \code{colData(x)}.
|
|
| 24 |
+} |
|
| 25 |
+\description{
|
|
| 26 |
+Swap the main Experiment for an alternative Experiment in a \linkS4class{SingleCellExperiment} object.
|
|
| 27 |
+} |
|
| 28 |
+\details{
|
|
| 29 |
+During the course of an analysis, we may need to perform operations on each of the alternative Experiments in turn. |
|
| 30 |
+This would require us to repeatedly call \code{altExp(x, name)} prior to running downstream functions on those Experiments.
|
|
| 31 |
+In such cases, it may be more convenient to switch the main Experiment with the desired alternative Experiments, |
|
| 32 |
+allowing a particular section of the analysis to be performed on the latter by default. |
|
| 33 |
+ |
|
| 34 |
+For example, the initial phases of the analysis might use the entire set of features. |
|
| 35 |
+At some point, we might want to focus only on a subset of features of interest, |
|
| 36 |
+but we do not want to discard the rest of the features. |
|
| 37 |
+This can be achieved by storing the subset as an alternative Experiment and swapping it with the main Experiment, |
|
| 38 |
+as shown in the Examples below. |
|
| 39 |
+} |
|
| 40 |
+\examples{
|
|
| 41 |
+example(SingleCellExperiment, echo=FALSE) # using the class example |
|
| 42 |
+ |
|
| 43 |
+# Let's say we defined a subset of genes of interest. |
|
| 44 |
+# We can save the feature set as its own altExp. |
|
| 45 |
+hvgs <- 1:10 |
|
| 46 |
+altExp(sce, "subset") <- sce[hvgs,] |
|
| 47 |
+ |
|
| 48 |
+# At some point, we want to do our analysis on the HVGs only, |
|
| 49 |
+# but we want to hold onto the other features for later reference. |
|
| 50 |
+sce <- swapAltExp(sce, name="subset", saved="all") |
|
| 51 |
+sce |
|
| 52 |
+ |
|
| 53 |
+# Once we're done, it is straightforward to switch back. |
|
| 54 |
+swapAltExp(sce, "all") |
|
| 55 |
+} |
|
| 56 |
+\seealso{
|
|
| 57 |
+\code{\link{altExps}}, for a description of the alternative Experiment concept.
|
|
| 58 |
+} |
|
| 59 |
+\author{
|
|
| 60 |
+Aaron Lun |
|
| 61 |
+} |