internals: Internal SingleCellExperiment functions

In LTLA/SingleCellExperiment: S4 Classes for Single Cell Data

Internal SingleCellExperiment functions

Description

Methods to get or set internal fields from the SingleCellExperiment class. Thse functions are intended for package developers who want to add protected fields to a SingleCellExperiment. They should not be used by ordinary users of the SingleCellExperiment package.

Getters

In the following code snippets, x is a SingleCellExperiment.

int_elementMetadata(x):

Returns a DataFrame of internal row metadata, with number of rows equal to nrow(x). This is analogous to the user-visible rowData.

int_colData(x):

Returns a DataFrame of internal column metadata, with number of rows equal to ncol(x). This is analogous to the user-visible colData.

int_metadata(x):

Returns a list of internal metadata, analogous to the user-visible metadata.

It may occasionally be useful to return both the visible and the internal colData in a single DataFrame. This is facilitated by the following methods:

rowData(x, ..., internal=FALSE):

Returns a DataFrame of the user-visible row metadata. If internal=TRUE, the internal row metadata is added column-wise to the user-visible metadata. A warning is emitted if the user-visible metadata column names overlap with the internal fields. Any arguments in ... are passed to rowData,SummarizedExperiment-method.

colData(x, ..., internal=FALSE):

Returns a DataFrame of the user-visible column metadata. If internal=TRUE, the internal column metadata is added column-wise to the user-visible metadata. A warning is emitted if the user-visible metadata column names overlap with the internal fields. Any arguments in ... are passed to colData,SummarizedExperiment-method.

Setters

In the following code snippets, x is a SingleCellExperiment.

int_elementMetadata(x) <- value:

Replaces the internal row metadata with value, a DataFrame with number of rows equal to nrow(x). This is analogous to the user-visible rowData<-.

int_colData(x) <- value:

Replaces the internal column metadata with value, a DataFrame with number of rows equal to ncol(x). This is analogous to the user-visible colData<-.

int_metadata(x) <- value:

Replaces the internal metadata with value, analogous to the user-visible metadata<-.

Comments

The internal metadata fields allow easy and extensible storage of additional elements that are parallel to the rows or columns of a SingleCellExperiment class. This avoids the need to specify new slots and adjust the subsetting/combining code for a new data element. For example, altExps and reducedDims are implemented as fields in the internal column metadata.

That these elements are internal is important as this ensures that the implementation details are abstracted away. Any user interaction with these internal fields should be done via the designated getter and setter methods, e.g., reducedDim and friends for retrieving or modifying reduced dimensions. This provides developers with more freedom to change the internal representation without breaking user code.

Package developers intending to use these methods to store their own content should read the development vignette for guidance.

Author(s)

Aaron Lun

See Also

colData, rowData and metadata for the user-visible equivalents.

Examples

example(SingleCellExperiment, echo=FALSE) # Using the class example
int_metadata(sce)$whee <- 1

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