calculatePCA {scater} | R Documentation

## Perform PCA on expression data

### Description

Perform a principal components analysis (PCA) on cells, based on the expression data in a SingleCellExperiment object.

### Usage

    calculatePCA(x, ...)

    ## S4 method for signature 'ANY'
    calculatePCA(x, ncomponents = 50, ntop = 500,
      subset_row = NULL, feature_set = NULL, scale = FALSE,
      scale_features = NULL, transposed = FALSE, BSPARAM = bsparam(),
      BPPARAM = SerialParam())

    ## S4 method for signature 'SummarizedExperiment'
    calculatePCA(x, ...,
      exprs_values = "logcounts")

    ## S4 method for signature 'SingleCellExperiment'
    calculatePCA(x, ...,
      exprs_values = "logcounts", dimred = NULL, use_dimred = NULL,
      n_dimred = NULL)

    ## S4 method for signature 'SingleCellExperiment'
    runPCA(x, ..., use_coldata = FALSE,
      altexp = NULL, name = "PCA")

### Arguments

`x` | For `calculatePCA`, a numeric matrix of log-expression values where rows are features and columns are cells. Alternatively, a SummarizedExperiment or SingleCellExperiment containing such a matrix. For `runPCA`, a SingleCellExperiment object containing such a matrix.
`...` | For the `calculatePCA` generic, additional arguments to pass to specific methods. For the SummarizedExperiment and SingleCellExperiment methods, additional arguments to pass to the ANY method. For `runPCA`, additional arguments to pass to `calculatePCA`.
`ncomponents` | Numeric scalar indicating the number of principal components to obtain.
`ntop` | Numeric scalar specifying the number of features with the highest variances to use for PCA, see `?"scater-red-dim-args"`.
`subset_row` | Vector specifying the subset of features to use for PCA, see `?"scater-red-dim-args"`.
`feature_set` | Deprecated, same as `subset_row`.
`scale` | Logical scalar, should the expression values be standardised? See `?"scater-red-dim-args"` for details.
`scale_features` | Deprecated, same as `scale` but with a different default.
`transposed` | Logical scalar, is `x` transposed with cells in rows? See `?"scater-red-dim-args"` for details.
`BSPARAM` | A BiocSingularParam object specifying which algorithm should be used to perform the PCA.
`BPPARAM` | A BiocParallelParam object specifying whether the PCA should be parallelized.
`exprs_values` | Integer scalar or string indicating which assay of `x` contains the expression values, see `?"scater-red-dim-args"`.
`dimred` | String or integer scalar specifying the existing dimensionality reduction results to use, see `?"scater-red-dim-args"`.
`use_dimred` | Deprecated, same as `dimred`.
`n_dimred` | Integer scalar or vector specifying the dimensions to use if `dimred` is specified, see `?"scater-red-dim-args"`.
`use_coldata` | Deprecated, use `runColDataPCA` instead.
`altexp` | String or integer scalar specifying an alternative experiment to use to compute the PCA, see `?"scater-red-dim-args"`.
`name` | String specifying the name to be used to store the result in the `reducedDims` of the output.

### Details

Fast approximate SVD algorithms like `BSPARAM=IrlbaParam()` or `RandomParam()` use a random initialization, after which they converge towards the exact PCs. This means that the result will change slightly across different runs. For full reproducibility, users should call `set.seed` prior to running `runPCA` with such algorithms. (Note that this includes `BSPARAM=bsparam()`, which uses approximate algorithms by default.)

### Value

A SingleCellExperiment object containing the first `ncomponents` principal coordinates for each cell. By default, this is stored in the `"PCA"` entry of the `reducedDims`. The proportion of variance explained by each PC is stored as a numeric vector in the `"percentVar"` attribute of the reduced dimension matrix.

### Author(s)

Aaron Lun, based on code by Davis McCarthy

### See Also

`runPCA`, for the underlying calculations.

`plotPCA`, to conveniently visualize the results.

`?"scater-red-dim-args"`, for a full description of various options.

### Examples

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

    example_sce <- runPCA(example_sce, scale_features=NULL)
    reducedDimNames(example_sce)
    head(reducedDim(example_sce))

[Package scater version 1.14.0 Index]