reducedDims: Reduced dimensions methods

In LTLA/SingleCellExperiment: S4 Classes for Single Cell Data

Reduced dimensions methods

Description

Methods to get or set dimensionality reduction results in a SingleCellExperiment object. These are typically used to store and retrieve low-dimensional representations of single-cell datasets. Each row of a reduced dimension result is expected to correspond to a column of the SingleCellExperiment object.

Getters

In the following examples, x is a SingleCellExperiment object.

reducedDim(x, type, withDimnames=TRUE):

Retrieves a matrix (or matrix-like object) containing reduced dimension coordinates for cells (rows) and dimensions (columns). type is either a string specifying the name of the dimensionality reduction result in x to retrieve, or a numeric scalar specifying the index of the desired result, defaulting to the first entry if missing.

If withDimnames=TRUE, row names of the output matrix are replaced with the column names of x.

reducedDimNames(x):

Returns a character vector containing the names of all dimensionality reduction results in x. This is guaranteed to be of the same length as the number of results, though the names may not be unique.

reducedDims(x, withDimnames=TRUE):

Returns a named List of matrices containing one or more dimensionality reduction results. Each result is a matrix (or matrix-like object) with the same number of rows as ncol(x).

If withDimnames=TRUE, row names of each matrix are replaced with the column names of x.

Single-result setter

reducedDim(x, type, withDimnames=TRUE) <- value will add or replace a dimensionality reduction result in a SingleCellExperiment object x. The value of type determines how the result is added or replaced:

• If type 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 type 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 type 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 matrix or matrix-like object with number of rows equal to ncol(x). Alternatively, if value is NULL, the result corresponding to type is removed from the object.

If withDimnames=TRUE, any non-NULL rownames(value) is checked against colnames(x) and a warning is emitted if they are not the same. Otherwise, any differences in the row names are ignored. This is inspired by the argument of the same name in assay<- but is more relaxed for practicality's sake - it raises a warning rather than an error and allows NULL rownames to pass through without complaints.

Other setters

In the following examples, x is a SingleCellExperiment object.

reducedDims(x, withDimnames=TRUE) <- value:

Replaces all dimensionality reduction results in x with those in value. The latter should be a list-like object containing any number of matrices or matrix-like objects with number of rows equal to ncol(x).

If value is named, those names will be used to name the dimensionality reduction results in x. Otherwise, unnamed results are assigned default names prefixed with "unnamed".

If value is NULL, all dimensionality reduction results in x are removed.

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

If withDimnames=TRUE, any non-NULL row names in each entry of value is checked against colnames(x) and a warning is emitted if they are not the same. Otherwise, any differences in the row names are ignored.

reducedDimNames(x) <- value:

Replaces all names for dimensionality reduction results in x with a character vector value. This should be of length equal to the number of results currently in x.

Storing dimensionality reduction metadata

When performing dimensionality reduction, we frequently generate metadata associated with a particular method. The typical example is the percentage of variance explained and the rotation matrix from PCA; model-based methods may also report some model information that can be used later to project points onto the embedding. Ideally, we would want to store this information alongside the coordinates themselves.

Our recommended approach is to store this metadata as attributes of the coordinate matrix. This is simple to do, easy to extract, and avoids problems with synchronization (when the coordinates are separated from the metadata). The biggest problem with this approach is that attributes are not retained when the matrix is subsetted or combined. To persist these attributes, we suggest wrapping the coordinates and metadata in a reduced.dim.matrix. More complex matrix-like objects like the LinearEmbeddingMatrix can also be used but may not be immediately compatible with downstream functions that expect an ordinary matrix.

The path less taken is to store the metadata in the mcols of the reducedDims List. This approach avoids the subsetting problem with the attributes but is less ideal as it separates the metadata from the coordinates. Such separation makes the metadata harder to find and remember to keep in sync with the coordinates when the latter changes. The structure of mcols is best suited to situations where there are some commonalities in the metadata across entries, but this rarely occurs for different dimensionality reduction strategies.

Author(s)

Aaron Lun and Kevin Rue-Albrecht

Examples

example(SingleCellExperiment, echo=FALSE)
reducedDim(sce, "PCA")
reducedDim(sce, "tSNE")
reducedDims(sce)

reducedDim(sce, "PCA") <- NULL
reducedDims(sce)

reducedDims(sce) <- SimpleList()
reducedDims(sce)

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