logNormCounts {scater} | R Documentation

## Compute log-normalized expression values

### Description

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

### Usage

    logNormCounts(x, ...)

    ## S4 method for signature 'SummarizedExperiment'
    logNormCounts(
      x,
      size_factors = NULL,
      log = TRUE,
      pseudo_count = 1,
      center_size_factors = TRUE,
      ...,
      exprs_values = "counts",
      name = NULL,
      BPPARAM = SerialParam()
    )

    ## S4 method for signature 'SingleCellExperiment'
    logNormCounts(
      x,
      size_factors = NULL,
      log = TRUE,
      pseudo_count = 1,
      center_size_factors = TRUE,
      ...,
      exprs_values = "counts",
      use_altexps = FALSE,
      name = NULL,
      BPPARAM = SerialParam()
    )

### 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.
`exprs_values` | 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.
`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 alternative experiments are not used.

### 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

    example_sce <- mockSCE()
    example_sce <- logNormCounts(example_sce)
    assayNames(example_sce)

[Package scater version 1.16.2 Index]