logNormCounts: Compute log-normalized expression values

Description Usage Arguments Details Value Author(s) See Also Examples

Description

Compute log-transformed normalized expression values from a count matrix in a SingleCellExperiment object.

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
28
29
30
31
32
33
34
35
36
37
logNormCounts(x, ...)

## S4 method for signature 'SummarizedExperiment'
logNormCounts(
  x,
  size.factors = NULL,
  log = TRUE,
  pseudo.count = 1,
  center.size.factors = TRUE,
  ...,
  assay.type = "counts",
  name = NULL,
  BPPARAM = SerialParam(),
  size_factors = NULL,
  pseudo_count = NULL,
  center_size_factors = NULL,
  exprs_values = NULL
)

## S4 method for signature 'SingleCellExperiment'
logNormCounts(
  x,
  size.factors = NULL,
  log = TRUE,
  pseudo.count = 1,
  center.size.factors = TRUE,
  ...,
  assay.type = "counts",
  use.altexps = FALSE,
  name = NULL,
  BPPARAM = SerialParam(),
  size_factors = NULL,
  pseudo_count = NULL,
  center_size_factors = NULL,
  exprs_values = NULL,
  use_altexps = NULL
)

Arguments

x

A SingleCellExperiment or SummarizedExperiment object containing a count matrix.

...

For the generic, additional arguments passed to specific methods.

For the methods, additional arguments passed to normalizeCounts.

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.

assay.type

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

name

String containing an assay name for storing the output normalized values. Defaults to "logcounts" when log=TRUE and "normcounts" otherwise.

BPPARAM

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

size_factors

Soft-deprecated equivalents to the arguments described previously.

pseudo_count

Soft-deprecated equivalents to the arguments described previously.

center_size_factors

Soft-deprecated equivalents to the arguments described previously.

exprs_values

Soft-deprecated equivalents to the arguments described previously.

use.altexps

Logical scalar indicating whether normalization should be performed for alternative experiments in x.

Alternatively, a character vector specifying the names of the alternative experiments to be normalized.

Alternatively NULL, in which case no calculations are performed on the alternative experiments.

use_altexps

Soft-deprecated equivalent to the argument above.

Details

This function is a convenience wrapper around normalizeCounts. It returns a SingleCellExperiment or SummarizedExperiment containing the normalized values in a separate assay. This makes it easier to perform normalization by avoiding book-keeping errors during a long analysis workflow.

If x is a SingleCellExperiment that contains alternative Experiments, normalized values can be computed and stored within each alternative experiment by setting use.altexps appropriately. By default, use.altexps=FALSE to avoid problems from attempting to library size-normalize alternative experiments that have zero total counts for some cells.

If size.factors=NULL, size factors are obtained following the rules in normalizeCounts. This is done independently for the main and alternative Experiments when use.altexps is specified, i.e. no information is shared between Experiments by default. However, if size.factors is supplied, it will override any size factors available in any Experiment.

Value

x is returned containing the (log-)normalized expression values in an additional assay named as name.

If x is a SingleCellExperiment, the size factors used for normalization are stored in sizeFactors. These are centered if center.size.factors=TRUE.

If x contains alternative experiments and use.altexps=TRUE, each of the alternative experiments in x will also contain an additional assay. This can be limited to particular altExps entries by specifying them in use.altexps.

Author(s)

Aaron Lun, based on code by Davis McCarthy

See Also

normalizeCounts, which is used to compute the normalized expression values.

Examples

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

# Standard library size normalization:
example_sce2 <- logNormCounts(example_sce)
assayNames(example_sce2)
logcounts(example_sce2)[1:5,1:5]

# Without logging, the assay is 'normcounts':
example_sce2 <- logNormCounts(example_sce, log=FALSE)
assayNames(example_sce2)
normcounts(example_sce2)[1:5,1:5]

# Pre-loading with size factors:
example_sce2 <- computeMedianFactors(example_sce)
example_sce2 <- logNormCounts(example_sce2)
logcounts(example_sce2)[1:5,1:5]

# Also normalizing the alternative experiments:
example_sce2 <- logNormCounts(example_sce, use.altexps="Spikes")
logcounts(altExp(example_sce2))[1:5,1:5]

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