logNormCounts: Compute log-normalized expression values
In scuttle: Single-Cell RNA-Seq Analysis Utilities

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

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

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
)

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

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.

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.

Aaron Lun, based on code by Davis McCarthy

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

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]