normalize: Normalise an SCESet object using pre-computed size factors

In dynverse/scaterlegacy: Single-cell analysis toolkit for gene expression data in R

Description

Compute normalised expression values from an SCESet object using the size factors stored in the object. Return the object with the normalised expression values added.

Usage

normalize.SCESet(object, exprs_values = NULL, logExprsOffset = NULL,
  centre_size_factors = TRUE, return_norm_as_exprs = TRUE)

## S4 method for signature 'SCESet'
normalize(object, exprs_values = NULL,
  logExprsOffset = NULL, centre_size_factors = TRUE,
  return_norm_as_exprs = TRUE)

normalise(...)

Arguments

object	an SCESet object.
exprs_values	character string indicating which slot of the assayData from the SCESet object should be used to compute log-transformed expression values. Valid options are 'counts', 'tpm', 'cpm' and 'fpkm'. Defaults to the first available value of the options in the order shown.
logExprsOffset	scalar numeric value giving the offset to add when taking log2 of normalised values to return as expression values. If NULL (default), then the value from object@logExprsOffset is used.
centre_size_factors	logical, should size factors centred at unity be stored in the returned object if exprs_values="counts"? Defaults to TRUE. Regardless, centred size factors will always be used to calculate exprs from count data. This argument is ignored for other exprs_values, where no size factors are used/modified.
return_norm_as_exprs	logical, should the normalised expression values be returned to the exprs slot of the object? Default is TRUE. If FALSE, values in the exprs slot will be left untouched. Regardless, normalised expression values will be returned in the norm_exprs(object) slot.
...	arguments passed to normalize when calling normalise.

Details

normalize is exactly the same as normalise, the option provided for those who have a preference for North American or British/Australian spelling.

Value

an SCESet object

Warning about centred size factors

Centring the size factors ensures that the computed exprs can be interpreted as being on the same scale as log-counts. This does not affect relative comparisons between cells in the same object, as all size factors are scaled by the same amount. However, if two different SCESet objects are run separately through normalize, the size factors in each object will be rescaled differently. This means that the size factors and exprs will not be comparable between objects.

This lack of comparability is not always obvious. For example, if we subsetted an existing SCESet, and ran normalize separately on each subset, the resulting exprs in each subsetted object would not be comparable to each other. This is despite the fact that all cells were originally derived from a single SCESet object.

In general, it is advisable to only compare size factors and exprs between cells in one SCESet object. If objects are to be combined, e.g., with mergeSCESet, new size factors should be computed using all cells in the combined object, followed by running normalize.

Author(s)

Davis McCarthy and Aaron Lun

Examples

data("sc_example_counts")
data("sc_example_cell_info")
pd <- new("AnnotatedDataFrame", data = sc_example_cell_info)
example_sceset <- newSCESet(countData = sc_example_counts, phenoData = pd)
keep_gene <- rowSums(counts(example_sceset)) > 0
example_sceset <- example_sceset[keep_gene,]

## Apply TMM normalisation taking into account all genes
example_sceset <- normaliseExprs(example_sceset, method = "TMM")
## Scale counts relative to a set of control features (here the first 100 features)
example_sceset <- normaliseExprs(example_sceset, method = "none",
feature_set = 1:100)

## normalize the object using the saved size factors
example_sceset <- normalize(example_sceset)

dynverse/scaterlegacy documentation built on Feb. 17, 2020, 5:07 a.m.