normalizeCounts: Compute normalized expression values

Description Usage Arguments Details Value Centering the size factors Downsampling instead of scaling Author(s) See Also Examples

Description

Compute (log-)normalized expression values by dividing counts for each cell by the corresponding size factor.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
normalizeCounts(x, ...)

## S4 method for signature 'ANY'
normalizeCounts(
  x,
  size.factors = NULL,
  log = TRUE,
  pseudo.count = 1,
  center.size.factors = TRUE,
  subset.row = NULL,
  downsample = FALSE,
  down.target = NULL,
  down.prop = 0.01,
  BPPARAM = SerialParam(),
  size_factors = NULL,
  pseudo_count = NULL,
  center_size_factors = NULL,
  subset_row = NULL,
  down_target = NULL,
  down_prop = NULL
)

## S4 method for signature 'SummarizedExperiment'
normalizeCounts(x, ..., assay.type = "counts", exprs_values = NULL)

## S4 method for signature 'SingleCellExperiment'
normalizeCounts(x, size.factors = NULL, ...)

Arguments

x

A numeric matrix-like object containing counts for cells in the columns and features in the rows.

Alternatively, a SingleCellExperiment or SummarizedExperiment object containing such a count matrix.

...

For the generic, arguments to pass to specific methods.

For the SummarizedExperiment method, further arguments to pass to the ANY or DelayedMatrix methods.

For the SingleCellExperiment method, further arguments to pass to the SummarizedExperiment method.

size.factors

A numeric vector of cell-specific size factors. Alternatively NULL, in which case the size factors are extracted or computed from x.

log

Logical scalar indicating whether normalized values should be log2-transformed.

pseudo.count

Numeric scalar specifying the pseudo-count to add when log-transforming expression values.

center.size.factors

Logical scalar indicating whether size factors should be centered at unity before being used.

subset.row

A vector specifying the subset of rows of x for which to return a result.

downsample

Logical scalar indicating whether downsampling should be performed prior to scaling and log-transformation.

down.target

Numeric scalar specifying the downsampling target when downsample=TRUE. If NULL, this is defined by down.prop and a warning is emitted.

down.prop

Numeric scalar between 0 and 1 indicating the quantile to use to define the downsampling target. Only used when downsample=TRUE.

BPPARAM

A BiocParallelParam object specifying how library size factor calculations should be parallelized. Only used if size.factors is not specified.

assay.type

A string or integer scalar specifying the assay of x containing the count matrix.

exprs_values, size_factors, pseudo_count, center_size_factors, subset_row, down_target, down_prop

Soft-deprecated equivalents to the arguments described previously.

Details

Normalized expression values are computed by dividing the counts for each cell by the size factor for that cell. This removes cell-specific scaling biases due to differences in sequencing coverage, capture efficiency or total RNA content. If log=TRUE, log-normalized values are calculated by adding pseudo.count to the normalized count and performing a log2-transformation.

If no size factors are supplied, they are determined automatically from x:

If size.factors are supplied, they will override any size factors present in x.

Value

A numeric matrix-like object containing (log-)normalized expression values. This has the same dimensions as x (unless subset.row is specified) and is of the same class as the original count matrix.

Centering the size factors

If center.size.factors=TRUE, size factors are centred at unity prior to calculation of normalized expression values. This ensures that the computed expression values can be interpreted as being on the same scale as original counts. We can then compare abundances between features normalized with different sets of size factors; the most common use of this fact is in the comparison between spike-in and endogenous abundances when modelling technical noise (see modelGeneVarWithSpikes package for an example).

More generally, when log=TRUE, centering of the size factors ensures that the value of pseudo.count can be interpreted as being on the same scale as the counts, i.e., the pseudo-count can actually be thought of as a count. This is important as it implies that the pseudo-count's impact will diminish as sequencing coverage improves. Thus, if the size factors are centered, differences between log-normalized expression values will more closely approximate the true log-fold change with increasing coverage, whereas this would not be true of other metrics like log-CPMs with a fixed offset.

The disadvantage of using centered size factors is that the expression values are not directly comparable across different calls to normalizeCounts, typically for multiple batches. In theory, this is not a problem for metrics like the CPM, but in practice, we have to apply batch correction methods anyway to perform any joint analysis - see multiBatchNorm for more details.

Downsampling instead of scaling

If downsample=TRUE, counts for each cell are randomly downsampled instead of being scaled. This is occasionally useful for avoiding artifacts caused by scaling count data with a strong mean-variance relationship. Each cell is downsampled according to the ratio between down.target and that cell's size factor. (Cells with size factors below the target are not downsampled and are directly scaled by this ratio.) If log=TRUE, a log-transformation is also performed after adding pseudo.count to the downsampled counts.

We automatically set down.target to the 1st percentile of size factors across all cells involved in the analysis, but this is only appropriate if the resulting expression values are not compared across different normalizeCounts calls. To obtain expression values that are comparable across different normalizeCounts calls (e.g., in modelGeneVarWithSpikes or multiBatchNorm), down_target should be manually set to a constant target value that can be considered a low size factor in every call.

Author(s)

Aaron Lun

See Also

logNormCounts, which wraps this function for convenient use with SingleCellExperiment instances.

librarySizeFactors, to compute the default size factors.

downsampleMatrix, to perform the downsampling.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
example_sce <- mockSCE()

# Standard scaling + log-transformation:
normed <- normalizeCounts(example_sce)
normed[1:5,1:5]

# Scaling without transformation:
normed <- normalizeCounts(example_sce, log=FALSE)
normed[1:5,1:5]

# Downscaling with transformation:
normed <- normalizeCounts(example_sce, downsample=TRUE)
normed[1:5,1:5]

# Using custom size factors:
with.meds <- computeMedianFactors(example_sce)
normed <- normalizeCounts(with.meds)
normed[1:5,1:5]

scuttle documentation built on Dec. 19, 2020, 2 a.m.