normaliseExprs {scater} | R Documentation

## Normalise expression expression levels for an SingleCellExperiment object

### Description

Compute normalised expression values from an SingleCellExperiment object and return the object with the normalised expression values added.

### Usage

    normaliseExprs(object, method = "none", design = NULL, feature_set = NULL,
      exprs_values = "counts", return_norm_as_exprs = TRUE, return_log = TRUE,
      ...)

    normalizeExprs(...)

### Arguments

`object` | an `SingleCellExperiment` object.
`method` | character string specified the method of calculating normalisation factors. Passed to `calcNormFactors`.
`design` | design matrix defining the linear model to be fitted to the normalised expression values. If not `NULL`, then the residuals of this linear model fit are used as the normalised expression values.
`feature_set` | character, numeric or logical vector indicating a set of features to use for calculating normalisation factors. If character, entries must all be in `featureNames(object)`. If numeric, values are taken to be indices for features. If logical, vector is used to index features and should have length equal to `nrow(object)`.
`exprs_values` | character string indicating which slot of the assayData from the `SingleCellExperiment` object should be used for the calculations. Valid options are `'counts'`, `'tpm'`, `'cpm'`, `'fpkm'` and `'exprs'`. Defaults to the first available value of these options in in order shown.
`return_norm_as_exprs` | logical, should the normalised expression values be returned to the `exprs` slot of the object? Default is TRUE. If FALSE, values in the `exprs` slot will be left untouched. Regardless, normalised expression values will be returned to the `norm_exprs` slot of the object.
`return_log` | logical(1), should normalized values be returned on the log scale? Default is `TRUE`. If `TRUE` and `return_norm_as_exprs` is `TRUE` then normalised output is stored as `"logcounts"` in the returned object; if `TRUE` and `return_norm_as_exprs` is `FALSE` then normalised output is stored as `"norm_exprs"`; if `FALSE` output is stored as `"normcounts"`
`...` | arguments passed to `normaliseExprs` (in the case of `normalizeExprs`) or to `calcNormFactors`.

### Details

This function allows the user to compute normalised expression values from an SingleCellExperiment object. The 'raw' values used can be the values in the `'counts'` (default), or another specified assay slot of the SingleCellExperiment. Normalised expression values are computed through `normalizeSCE` and are on the log2-scale by default (if `return_log` is TRUE), with an offset defined by the `metadata(object)$log.exprs.offset` value in the SingleCellExperiment object. These are added to the `'norm_exprs'` slot of the returned object. If `'exprs_values'` argument is `'counts'` and `return_log` is `FALSE` a `'normcounts'` slot is added, containing normalised counts-per-million values.

If the raw values are counts, this function will compute size factors using methods in `calcNormFactors`. Library sizes are multiplied by size factors to obtain an "effective library size" before calculation of the aforementioned normalized expression values. If `feature_set` is specified, only the specified features will be used to calculate the size factors.

If the user wishes to remove the effects of certain explanatory variables, then the `'design'` argument can be defined. The `design` argument must be a valid design matrix, for example as produced by `model.matrix`, with the relevant variables. A linear model is then fitted using `lmFit` on expression values after any size-factor and library size normalisation as descrived above. The returned values in `'norm_exprs'` are the residuals from the linear model fit.

After normalisation, normalised expression values can be accessed with the `norm_exprs` function (with corresponding accessor functions for counts, tpm, fpkm, cpm). These functions can also be used to assign normalised expression values produced with external tools to a SingleCellExperiment object.

`normalizeExprs` is exactly the same as `normaliseExprs`, provided for those who prefer North American spelling.

### Value

an SingleCellExperiment object

### Author(s)

Davis McCarthy

### Examples

    data("sc_example_counts")
    data("sc_example_cell_info")
    example_sce <- SingleCellExperiment(
    assays = list(counts = sc_example_counts), colData = sc_example_cell_info)
    keep_gene <- rowSums(counts(example_sce)) > 0
    example_sce <- example_sce[keep_gene,]

    ## Apply TMM normalisation taking into account all genes
    example_sce <- normaliseExprs(example_sce, method = "TMM")
    ## Scale counts relative to a set of control features (here the first 100 features)
    example_sce <- normaliseExprs(example_sce, method = "none",
    feature_set = 1:100)

[Package scater version 1.6.3 Index]