1 Introduction

This document gives an introduction to and overview of the quality control functionality of the scater package. scater contains tools to help with the analysis of single-cell transcriptomic data, focusing on RNA-seq data. The package features:

• Use of the SingleCellExperiment class as a data container for interoperability with a wide range of other Bioconductor packages;
• Functions to import kallisto and Salmon results;
• Simple calculation of many quality control metrics from the expression data;
• Many tools for visualising scRNA-seq data, especially diagnostic plots for quality control;
• Subsetting and many other methods for filtering out problematic cells and features;
• Methods for identifying important experimental variables and normalising data ahead of downstream statistical analysis and modeling.

2 Creating a SingleCellExperiment object

We assume that you have a matrix containing expression count data summarised at the level of some features (gene, exon, region, etc.). First, we create a SingleCellExperiment object containing the data, as demonstrated below with some example data ("sc_example_counts") and metadata ("sc_example_cell_info"): Rows of the object correspond to features, while columns correspond to samples, i.e., cells in the context of single-cell ’omics data.

library(scater)
data("sc_example_counts")
data("sc_example_cell_info")
example_sce <- SingleCellExperiment(
    assays = list(counts = sc_example_counts), 
    colData = sc_example_cell_info
)
example_sce

## class: SingleCellExperiment 
## dim: 2000 40 
## metadata(0):
## assays(1): counts
## rownames(2000): Gene_0001 Gene_0002 ... Gene_1999 Gene_2000
## rowData names(0):
## colnames(40): Cell_001 Cell_002 ... Cell_039 Cell_040
## colData names(4): Cell Mutation_Status Cell_Cycle Treatment
## reducedDimNames(0):
## spikeNames(0):

We usually expect (raw) count data to be labelled as "counts" in the assays, which can be easily retrieved with the counts accessor. Getters and setters are also provided for exprs, tpm, cpm, fpkm and versions of these with the prefix norm_.

str(counts(example_sce))

Row and column-level metadata are easily accessed (or modified) as shown below. There are also dedicated getters and setters for spike-in specifiers (isSpike); size factor values (sizeFactors); and reduced dimensionality results (reducedDim).

example_sce$whee <- sample(LETTERS, ncol(example_sce), replace=TRUE)
colData(example_sce)

## DataFrame with 40 rows and 5 columns
##                 Cell Mutation_Status  Cell_Cycle   Treatment        whee
##          <character>     <character> <character> <character> <character>
## Cell_001    Cell_001        positive           S      treat1           W
## Cell_002    Cell_002        positive          G0      treat1           O
## Cell_003    Cell_003        negative          G1      treat1           W
## Cell_004    Cell_004        negative           S      treat1           Z
## Cell_005    Cell_005        negative          G1      treat2           W
## ...              ...             ...         ...         ...         ...
## Cell_036    Cell_036        negative          G0      treat1           S
## Cell_037    Cell_037        negative          G0      treat1           R
## Cell_038    Cell_038        negative          G0      treat2           S
## Cell_039    Cell_039        negative          G1      treat1           R
## Cell_040    Cell_040        negative          G0      treat2           Q

rowData(example_sce)$stuff <- runif(nrow(example_sce))
rowData(example_sce)

## DataFrame with 2000 rows and 1 column
##                        stuff
##                    <numeric>
## Gene_0001   0.80085068452172
## Gene_0002  0.202237056568265
## Gene_0003  0.491804076358676
## Gene_0004  0.091127741150558
## Gene_0005  0.540604811627418
## ...                      ...
## Gene_1996   0.25665649631992
## Gene_1997  0.414263135753572
## Gene_1998  0.864102468360215
## Gene_1999 0.0602115865331143
## Gene_2000  0.778497750638053

Subsetting is very convenient with this class, as both data and metadata are processed in a synchronized manner. For example, we can filter out features (genes) that are not expressed in any cells:

keep_feature <- rowSums(counts(example_sce) > 0) > 0
example_sce <- example_sce[keep_feature,]

More details about the SingleCellExperiment class can be found in the documentation for SingleCellExperiment package.

3 Calculating a variety of expression values

We calculate counts-per-million using the aptly-named calculateCPM function. The output is most appropriately stored as an assay named "cpm" in the assays of the SingleCellExperiment object.

cpm(example_sce) <- calculateCPM(example_sce)

Another option is to use the normalize function, which calculates log₂-transformed normalized expression values. This is done by dividing each count by its size factor (or scaled library size, if no size factors are defined), adding a pseudo-count and log-transforming. The resulting values can be interpreted on the same scale as log-transformed counts, and are stored in "logcounts".

example_sce <- normalize(example_sce)
assayNames(example_sce)

## [1] "counts"    "cpm"       "logcounts"

Note that exprs is a synonym for logcounts when accessing or setting data. This is done for backwards compatibility with older verions of scater.

identical(exprs(example_sce), logcounts(example_sce))

## [1] TRUE

Of course, users can construct any arbitrary matrix of the same dimensions as the count matrix and store it as an assay.

assay(example_sce, "is_expr") <- counts(example_sce)>0

The calcAverage function will compute the average count for each gene after scaling each cell’s counts by its size factor. If size factors are not available, it will compute a size factor from the library size.

head(calcAverage(example_sce))

##  Gene_0001  Gene_0002  Gene_0003  Gene_0004  Gene_0005  Gene_0006 
## 305.551749 325.719897 183.090462 162.143201   1.231123 187.167913

4 Other methods of data import

Count matrices stored as CSV files or equivalent can be easily read into R session using read.table from utils or fread from the data.table package. It is advisable to coerce the resulting object into a matrix before storing it in a SingleCellExperiment object.

For large data sets, the matrix can be read in chunk-by-chunk with progressive coercion into a sparse matrix from the Matrix package. This is performed using readSparseCounts and reduces memory usage by not explicitly storing zeroes in memory.

Data from 10X Genomics experiments can be read in using the read10xCounts function from the DropletUtils package. This will automatically generate a SingleCellExperiment with a sparse matrix, see the documentation for more details.

scater also provides wrapper functions readSalmonResults or readKallistoResults to import transcript abundances from the kallisto and Salmon pseudo-aligners. This is done using methods from the tximport package.

5 Transitioning from the SCESet class

As of July 2017, scater has switched from the SCESet class previously defined within the package to the more widely applicable SingleCellExperiment class. From Bioconductor 3.6 (October 2017), the release version of scater will use SingleCellExperiment. SingleCellExperiment is a more modern and robust class that provides a common data structure used by many single-cell Bioconductor packages. Advantages include support for sparse data matrices and the capability for on-disk storage of data to minimise memory usage for large single-cell datasets.

It should be straight-forward to convert existing scripts based on SCESet objects to SingleCellExperiment objects, with key changes outlined immediately below.

• The functions toSingleCellExperiment and updateSCESet (for backwards compatibility) can be used to convert an old SCESet object to a SingleCellExperiment object;
• Create a new SingleCellExperiment object with the function SingleCellExperiment (actually less fiddly than creating a new SCESet);
• scater functions have been refactored to take SingleCellExperiment objects, so once data is in a SingleCellExperiment object, the user experience is almost identical to that with the SCESet class.

Users may need to be aware of the following when updating their own scripts:

• Cell names can now be accessed/assigned with the colnames function (instead of sampleNames or cellNames for an SCESet object);
• Feature (gene/transcript) names should now be accessed/assigned with the rownames function (instead of featureNames);
• Cell metadata, stored as phenoData in an SCESet, corresponds to colData in a SingleCellExperiment object and is accessed/assigned with the colData function (this replaces the pData function);
• Individual cell-level variables can still be accessed with the $ operator (e.g. sce$total_counts);
• Feature metadata, stored as featureData in an SCESet, corresponds to rowData in a SingleCellExperiment object and is accessed/assigned with the rowData function (this replaces the fData function);
• plotScater, which produces a cumulative expression, overview plot, replaces the generic plot function for SCESet objects.