SCE-internals {SingleCellExperiment} | R Documentation

## 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 `colData`.

`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 `rowData`.

`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 `colData<-`.

`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 `rowData<-`.

`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

[Package SingleCellExperiment version 1.8.0 Index]