perCellQCMetrics {scater} | R Documentation

## Compute per-cell quality control metrics for a count matrix or a SingleCellExperiment.

### Description

Compute per-cell quality control metrics for a count matrix or a SingleCellExperiment.

### Usage

    perCellQCMetrics(x, ...)

    ## S4 method for signature 'ANY'
    perCellQCMetrics(
      x,
      subsets = NULL,
      percent_top = c(50, 100, 200, 500),
      detection_limit = 0,
      BPPARAM = SerialParam(),
      flatten = TRUE
    )

    ## S4 method for signature 'SummarizedExperiment'
    perCellQCMetrics(x, ..., exprs_values = "counts")

    ## S4 method for signature 'SingleCellExperiment'
    perCellQCMetrics(
      x,
      subsets = NULL,
      percent_top = c(50, 100, 200, 500),
      ...,
      flatten = TRUE,
      exprs_values = "counts",
      use_altexps = TRUE
    )

### Arguments

`x` | A numeric matrix of counts with cells in columns and features in rows. Alternatively, a SummarizedExperiment or SingleCellExperiment object containing such a matrix.
`...` | For the generic, further arguments to pass to specific methods. For the SummarizedExperiment and SingleCellExperiment methods, further arguments to pass to the ANY method.
`subsets` | A named list containing one or more vectors (a character vector of feature names, a logical vector, or a numeric vector of indices), used to identify interesting feature subsets such as ERCC spike-in transcripts or mitochondrial genes.
`percent_top` | An integer vector. Each element is treated as a number of top genes to compute the percentage of library size occupied by the most highly expressed genes in each cell.
`detection_limit` | A numeric scalar specifying the lower detection_limit for expression.
`BPPARAM` | A BiocParallelParam object specifying whether the QC calculations should be parallelized.
`flatten` | Logical scalar indicating whether the nested DataFrames in the output should be flattened.
`exprs_values` | A string or integer scalar indicating which `assays` in the `x` contains the count matrix.
`use_altexps` | Logical scalar indicating whether QC statistics should be computed for alternative Experiments in `x`. If `TRUE`, statistics are computed for all alternative experiments. Alternatively, an integer or character vector specifying the alternative Experiments to use to compute QC statistics. Alternatively `NULL`, in which case alternative experiments are not used.

### Details

This function calculates useful QC metrics for identification and removal of potentially problematic cells. Obvious per-cell metrics are the sum of counts (i.e., the library size) and the number of detected features. The percentage of counts in the top features also provides a measure of library complexity.

If `subsets` is specified, these statistics are also computed for each subset of features. This is useful for investigating gene sets of interest, e.g., mitochondrial genes, Y chromosome genes. These statistics are stored as nested DataFrames in the `subsets` field of the output. For example, if the input `subsets` contained `"Mito"` and `"Sex"`, the output would look like:

      output
      |-- sum
      |-- detected
      |-- percent_top
      +-- subsets
          |-- Mito
          |   |-- sum
          |   |-- detected
          |   +-- percent
          +-- Sex
              |-- sum
              |-- detected
              +-- percent

Here, the `percent` field contains the percentage of each cell's count sum assigned to each subset.

If `use_altexps` is `TRUE`, the same statistics are computed for each alternative experiment in `x`. This can also be an integer or character vector specifying the alternative Experiments to use. These statistics are also stored as nested DataFrames, this time in the `altexps` field of the output. For example, if `x` contained the alternative Experiments `"Spike"` and `"Ab"`, the output would look like:

      output
      |-- sum
      |-- detected
      |-- percent_top
      +-- altexps
      |   |-- Spike
      |   |   |-- sum
      |   |   |-- detected
      |   |   +-- percent.total
      |   +-- Ab
      |       |-- sum
      |       |-- detected
      |       +-- percent.total
      +-- total

The `total` field contains the total sum of counts for each cell across the main and alternative Experiments. The `percent` field contains the percentage of the total count in each alternative Experiment for each cell.

If `flatten=TRUE`, the nested DataFrames are flattened by concatenating the column names with underscores. This means that, say, the `subsets$Mito$sum` nested field becomes the top-level `subsets_Mito_sum` field. A flattened structure is more convenient for end-users performing interactive analyses, but less convenient for programmatic access as artificial construction of strings is required.

### Value

A DataFrame of QC statistics where each row corresponds to a column in `x`. This contains the following fields:

- `sum`: numeric, the sum of counts for each cell.

- `detected`: numeric, the number of observations above `detection_limit`.

If `flatten=FALSE`, the DataFrame will contain the additional columns:

- `percent_top`: numeric matrix, the percentage of counts assigned to the percent_topage of most highly expressed genes. Each column of the matrix corresponds to an entry of the sorted `percent_top`, in increasing order.

- `subsets`: A nested DataFrame containing statistics for each subset, see Details.

- `altexps`: A nested DataFrame containing statistics for each alternative experiment, see Details. This is only returned for the SingleCellExperiment method.

- `total`: numeric, the total sum of counts for each cell across main and alternative Experiments. This is only returned for the SingleCellExperiment method.

If `flatten=TRUE`, nested matrices and DataFrames are flattened to remove the hierarchical structure from the output DataFrame.

### Author(s)

Aaron Lun

### See Also

`addPerCellQC`, to add the QC metrics to the column metadata.

### Examples

    example_sce <- mockSCE()
    stats <- perCellQCMetrics(example_sce)
    stats

    # With subsets.
    stats2 <- perCellQCMetrics(example_sce, subsets=list(Mito=1:10),
        flatten=FALSE)
    stats2$subsets

    # With alternative Experiments.
    pretend.spike <- ifelse(seq_len(nrow(example_sce)) < 10, "Spike", "Gene")
    alt_sce <- splitAltExps(example_sce, pretend.spike)
    stats3 <- perCellQCMetrics(alt_sce, flatten=FALSE)
    stats3$altexps

[Package scater version 1.16.2 Index]