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, 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 `cbind`ed 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 `cbind`ed 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

### 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.16.0 Index]