altExps {SingleCellExperiment} | 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, withColData=TRUE)`:

  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=TRUE)`:

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

[Package SingleCellExperiment version 1.8.0 Index]