getExplanatoryPCs {scater} | R Documentation

## Per-PC variance explained by a variable

### Description

Compute, for each principal component, the percentage of variance that is explained by one or more variables of interest.

### Usage

    getExplanatoryPCs(x, dimred = "PCA", use_dimred = NULL,
      n_dimred = 10, ncomponents = NULL, rerun = FALSE,
      run_args = list(), ...)

### Arguments

`x` | A SingleCellExperiment object containing dimensionality reduction results.
`dimred` | String or integer scalar specifying the field in `reducedDims(x)` that contains the PCA results.
`use_dimred` | Deprecated, same as `dimred`.
`n_dimred` | Integer scalar specifying the number of the top principal components to use.
`ncomponents` | Deprecated, same as `n_dimred`.
`rerun` | Deprecated. Logical scalar indicating whether the PCA should be repeated, even if pre-computed results are already present.
`run_args` | Deprecated. A named list of arguments to pass to `runPCA`.
`...` | Additional arguments passed to `getVarianceExplained`.

### Details

This function computes the percentage of variance in PC scores that is explained by variables in the sample-level metadata. It allows identification of important PCs that are driven by known experimental conditions, e.g., treatment, disease. PCs correlated with technical factors (e.g., batch effects, library size) can also be detected and removed prior to further analysis.

By default, the function will attempt to use pre-computed PCA results in `object`. This is done by taking the top `n_dimred` PCs from the matrix specified by `dimred`. If these are not available or if `rerun=TRUE`, the function will rerun the PCA using `runPCA`; however, this mode is deprecated and users are advised to explicitly call `runPCA` themselves.

### Value

A matrix containing the percentage of variance explained by each factor (column) and for each PC (row).

### Author(s)

Aaron Lun

### See Also

`plotExplanatoryPCs`, to plot the results.

`getVarianceExplained`, to compute the variance explained.

### Examples

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

    r2mat <- getExplanatoryPCs(example_sce)

[Package scater version 1.14.0 Index]