logNormCounts {scuttle} | 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 = NULL,
      transform = c("log", "none", "asinh"),
      pseudo.count = 1,
      center.size.factors = TRUE,
      ...,
      subset.row = NULL,
      normalize.all = FALSE,
      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 = sizeFactors(x),
      log = NULL,
      transform = c("log", "none", "asinh"),
      pseudo.count = 1,
      center.size.factors = TRUE,
      ...,
      subset.row = NULL,
      normalize.all = FALSE,
      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 computed from `x`.
`log` | Logical scalar indicating whether normalized values should be log2-transformed. This is retained for back-compatibility and will override any setting of `transform`. Users should generally use `transform` instead to specify the transformation.
`transform` | String specifying the transformation (if any) to apply to the normalized expression values.
`pseudo.count` | Numeric scalar specifying the pseudo-count to add when `transform="log"`.
`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 normalized values. If `size.factors=NULL`, the size factors are also computed from this subset.
`normalize.all` | Logical scalar indicating whether to return normalized values for all genes. If `TRUE`, any non-`NULL` value for `subset.row` is only used to compute the size factors. Ignored if `subset.row=NULL` or `size.factors` is supplied.
`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 `transform="log"`, `"ashcounts"` when `transform="asinh"`, 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, use_altexps` | Deprecated, use `applySCE` instead (see Examples).

### 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 `NULL`, size factors are determined as described in `normalizeCounts`. `subset.row` and `normalize.all` have the same interpretation as for `normalizeCounts`.

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

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

    # 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 <- applySCE(example_sce, logNormCounts)
    logcounts(altExp(example_sce2))[1:5,1:5]

[Package scuttle version 1.2.1 Index]