colLabels: Get or set column labels

In drisso/SingleCellExperiment: S4 Classes for Single Cell Data

Get or set column labels

Description

Get or set column labels in an instance of a SingleCellExperiment class. Labels are expected to represent information about the the biological state of each cell.

Usage

## S4 method for signature 'SingleCellExperiment'
colLabels(x, onAbsence = "none")

## S4 replacement method for signature 'SingleCellExperiment'
colLabels(x, ...) <- value

Arguments

x	A SingleCellExperiment object.
onAbsence	String indicating an additional action to take when labels are absent: nothing ("none"), a warning ("warn") or an error ("error").
...	Additional arguments, currently ignored.
value	Any vector-like object of length equal to ncol(object), containing labels for all cells. Alternatively NULL, in which case existing label information is removed.

Details

A frequent task in single-cell data analyses is to label cells with some annotation, e.g., cluster identities, predicted cell type classifications and so on. In a SummarizedExperiment, the colData represents the ideal place for such annotations, which can be easily set and retrieved with standard methods, e.g., x$label <- my.labels.

That said, it is desirable to have some informal standardization of the name of the column used to store these annotations as this makes it easier to programmatically set sensible defaults for retrieval of the labels in downstream functions. To this end, the colLabels function will get or set labels from the "label" field of the colData. This considers the use case where there is a “primary” set of labels that represents the default grouping of cells in downstream analyses.

To illustrate, let's say we have a downstream function that accepts a SingleCellExperiment object and requires labels. When defining our function, we can set colLabels(x) as the default value for our label argument. This pattern is useful as it accommodates on-the-fly changes to a secondary set of labels in x without requiring the user to run colLabels(x) <- second.labels, while facilitating convenient use of the primary labels by default.

For developers, onAbsence is provided to make it easier to mandate that x actually has labels. This avoids silent NULL values that flow to the rest of the function and make debugging difficult.

Value

For colLabels, a vector or equivalent is returned containing label assignments for all cells. If no labels are available, a NULL is returned (and/or a warning or error, depending on onAbsence).

For colLabels<-, a modified x is returned with labels in its colData.

Author(s)

Aaron Lun

See Also

SingleCellExperiment, for the underlying class definition.

Examples

example(SingleCellExperiment, echo=FALSE) # Using the class example
colLabels(sce) <- sample(LETTERS, ncol(sce), replace=TRUE)
colLabels(sce)

drisso/SingleCellExperiment documentation built on Nov. 12, 2024, 7:01 a.m.