Overview

scrapper implements bindings to C++ code for analyzing single-cell data, mostly from the libscran libraries. Each function performs an individual analysis step ranging from quality control to clustering and marker detection. Users can also conveniently perform end-to-end analyses with a single call to the analyze.se() function.

Basic analysis

Let’s fetch a small single-cell RNA-seq dataset for demonstration purposes:

library(scRNAseq)
sce.z <- ZeiselBrainData()
sce.z

## class: SingleCellExperiment 
## dim: 20006 3005 
## metadata(0):
## assays(1): counts
## rownames(20006): Tspan12 Tshz1 ... mt-Rnr1 mt-Nd4l
## rowData names(1): featureType
## colnames(3005): 1772071015_C02 1772071017_G12 ... 1772066098_A12
##   1772058148_F03
## colData names(9): tissue group # ... level1class level2class
## reducedDimNames(0):
## mainExpName: gene
## altExpNames(2): repeat ERCC

We run it through the scrapper analysis pipeline. This performs the usual steps - quality control, normalization, selection of highly variable genes, PCA, clustering, visualization and marker detection, see the OSCA book for more theoretical details.

library(scrapper)
is.mito <- grep("^mt-", rownames(sce.z))
results <- analyze.se(
    sce.z,
    rna.qc.subsets=list(Mito=is.mito),
    num.threads=2 # limit number of threads to keep R CMD check happy.
)
results$x # most outputs are stored in a copy of the input SingleCellExperiment. 

## class: SingleCellExperiment 
## dim: 20006 2874 
## metadata(2): qc PCA
## assays(2): counts logcounts
## rownames(20006): Tspan12 Tshz1 ... mt-Rnr1 mt-Nd4l
## rowData names(6): featureType means ... residuals hvg
## colnames(2874): 1772071015_C02 1772071017_G12 ... 1772063068_D01
##   1772066098_A12
## colData names(15): tissue group # ... sizeFactor graph.cluster
## reducedDimNames(3): PCA TSNE UMAP
## mainExpName: gene
## altExpNames(2): repeat ERCC

Now we can have a look at some of the results. For example, we can make a t-SNE plot:

library(scater)
plotReducedDim(results$x, "TSNE", colour_by="graph.cluster")

We can also look at the markers defining each cluster:

# Ordering by the median AUC across pairwise comparisons involving the cluster.
previewMarkers(results$markers$rna[[1]], order.by="auc.median")

## DataFrame with 10 rows and 4 columns
##             mean  detected       lfc auc.median
##        <numeric> <numeric> <numeric>  <numeric>
## Gad1     4.79503  1.000000   4.56949   0.997684
## Gad2     4.44192  0.996503   4.25766   0.995434
## Ndrg4    4.40310  0.996503   2.59179   0.990182
## Stmn3    4.71546  0.993007   2.64538   0.986791
## Tspyl4   3.36568  1.000000   2.15128   0.983035
## Syp      2.79635  0.993007   1.53131   0.976301
## Rab3a    3.34302  0.989510   1.82740   0.975972
## Scg5     4.74990  1.000000   2.06392   0.975421
## Snap25   5.40529  1.000000   2.61350   0.974922
## Slc6a1   3.75820  0.993007   3.08908   0.974192

analyze.se() can also be broken down to its component functions for further customization:

test <- sce.z
test <- quickRnaQc.se(test, subsets=list(mt=is.mito), num.threads=2)
test <- test[,test$keep]
test <- normalizeRnaCounts.se(test, size.factors=test$sum)
test <- chooseRnaHvgs.se(test, num.threads=2)
test <- runPca.se(test, features=rowData(test)$hvg, num.threads=2)
test <- runAllNeighborSteps.se(test, num.threads=2)
markers <- scoreMarkers.se(test, groups=test$clusters, num.threads=2)

Blocking on batches

Let’s fetch another brain dataset and combine it with the previous one.

sce.t <- TasicBrainData()

# Only using the common genes in both datasets.
common <- intersect(rownames(sce.z), rownames(sce.t))
combined <- combineCols(sce.t[common,], sce.z[common,])
block <- rep(c("tasic", "zeisel"), c(ncol(sce.t), ncol(sce.z)))

We set block= in each step to account for the batch structure. This ensures that the various calculations are not affected by inter-block differences. It also uses MNN correction to batch effects in the low-dimensional space prior to further analyses.

# No mitochondrial genes in the combined set, so we'll just skip it.
blocked_res <- analyze.se(combined, block=block, num.threads=2)

Hopefully, the correction is able to get rid of the batch effect and merge the datasets together.

plotReducedDim(blocked_res$x, "TSNE", colour_by="block")

We can also check the distribution of clusters across batches. The presence of batch-specific clusters might indicate that the batch effect was not fully removed; or they might represent cell types that are unique to one of the studies, who knows.

table(blocked_res$x$graph.cluster, blocked_res$x$block)

##     
##      tasic zeisel
##   1    122     90
##   2    477     70
##   3    364    130
##   4    183    128
##   5     43    362
##   6     22    121
##   7     91     99
##   8     20    150
##   9     31     12
##   10    48     18
##   11   248    106
##   12    20    701
##   13     7    252
##   14     1    213
##   15     8     87
##   16     0    463

Finally, some markers for another cluster:

previewMarkers(blocked_res$markers$rna[[1]])

## DataFrame with 10 rows and 3 columns
##             mean  detected       lfc
##        <numeric> <numeric> <numeric>
## Gad1     4.99380  1.000000   3.26141
## Igf1     4.22957  0.990566   3.22416
## Synpr    5.06317  0.985849   3.61784
## Cnr1     6.27028  1.000000   4.46956
## Slc6a1   4.07537  1.000000   2.19651
## Gad2     3.45237  1.000000   2.42218
## Vstm2a   3.37646  0.995283   2.26351
## Vip      5.68657  0.863208   5.08033
## Nap1l5   3.72545  1.000000   2.35075
## Nrxn3    4.17803  1.000000   2.27554

We can also compute pseudo-bulk profiles for each cluster-dataset combination, e.g., for differential expression analyses.

aggregates <- aggregateAcrossCells.se(
    blocked_res$x,
    list(cluster=blocked_res$x$graph.cluster, dataset=blocked_res$x$block)
)
aggregates

## class: SummarizedExperiment 
## dim: 18698 31 
## metadata(1): aggregated
## assays(2): sums detected
## rownames(18698): Tspan12 Tshz1 ... Uty Usp9y
## rowData names(6): featureType means ... residuals hvg
## colnames: NULL
## colData names(30): factor.cluster factor.dataset ... block
##   graph.cluster

Combining multiple modalities

Let’s fetch a single-cell dataset with both RNA-seq and CITE-seq data. To keep the run-time short, we’ll only consider the first 5000 cells.

sce.s <- StoeckiusHashingData(mode=c("human", "adt1", "adt2"))

sce.s <- sce.s[,1:5000]

# Combining the various ADT-related alternative experiments into a single object.
altExp(sce.s, "all.adts") <- rbind(altExp(sce.s, "adt1"), altExp(sce.s, "adt2"))
altExp(sce.s, "adt1") <- altExp(sce.s, "adt2") <- NULL

sce.s

## class: SingleCellExperiment 
## dim: 27679 5000 
## metadata(0):
## assays(1): counts
## rownames(27679): A1BG A1BG-AS1 ... hsa-mir-8072 snoU2-30
## rowData names(0):
## colnames(5000): TGCCAAATCTCTAAGG ACTGCTCAGGTGTTAA ... CGCTATCGTCCGTCAG
##   GGCGACTGTAAGGGAA
## colData names(0):
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(1): all.adts

We specify adt.altexp= to indicate that one of the alternative experiments contains ADT data. This instructs the analysis to use data from both modalities during clustering and visualization.

is.mito <- grepl("^MT-", rownames(sce.s))
is.igg <- grepl("^IgG", rownames(altExp(sce.s, 'all.adts')))
multi_res <- analyze.se(
    sce.s,
    adt.altexp="all.adts",
    rna.qc.subsets=list(mito=is.mito),
    adt.qc.subsets=list(igg=is.igg),
    num.threads=2
)

Here’s an obligatory plot:

plotReducedDim(multi_res$x, "UMAP", colour_by="graph.cluster")

We can inspect the top markers among the ADTs for a cluster:

# By default, markers are sorted by the mean Cohen's d.
# We just replace the column name when printing the dataframe here.
previewMarkers(multi_res$markers$adt[[5]], c(effect="cohens.d.mean"))

## DataFrame with 10 rows and 1 column
##                                  effect
##                               <numeric>
## CD4-TAGACAGCTG                3.6884442
## CD3-TCTTCGTCCA                0.7931371
## CD45RA-AGTCCATTGG             0.1395605
## CCR7-GTAAACCGCA               0.0754008
## IgG_control-CATGATTGGCTC     -0.0190229
## IgM_control-AAGCGCTTGGCA     -0.0508764
## IgG2b_2_control-CATCGGTGTACA -0.1411518
## PD-1-GTACTTCCAG              -0.3935047
## IgG1_2_control-GTCTAGACTTCG  -0.5329377
## CD8-AGATGAACCC               -0.5452329

… along with the RNA markers, as before.

# Using the delta-detected to focus on silent-to-expressed genes.
previewMarkers(multi_res$markers$rna[[5]], order.by="delta.detected.mean")

## DataFrame with 10 rows and 4 columns
##              mean  detected       lfc delta.detected.mean
##         <numeric> <numeric> <numeric>           <numeric>
## ENAH      1.36986   0.94375  0.820350            0.598778
## CNN3      2.09056   0.97500  1.224571            0.597853
## WBP5      2.01220   0.98125  1.145416            0.594153
## PLS3      1.75284   0.96875  1.012275            0.591067
## CENPV     1.90134   0.96250  1.130238            0.589109
## S100A13   1.35069   0.93750  0.793204            0.588513
## PCBD1     1.70390   0.96875  0.931640            0.587040
## UCHL1     1.71843   0.96250  0.954069            0.585129
## CALD1     1.60756   0.93750  0.957796            0.579067
## RDX       1.26275   0.93125  0.739840            0.577328

Other useful functions

The runAllNeighborSteps() fucntion will run runUmap(), runTsne(), buildSnnGraph() and clusterGraph() in a single call. This runs the UMAP/t-SNE iterations and the clustering in parallel to maximize use of multiple threads.

The scoreGeneSet() function will compute a gene set score based on the input expression matrix. This can be used to summarize the activity of pathways into a single per-cell score for visualization.

The subsampleByNeighbors() function will deterministically select a representative subset of cells based on their local neighborhood. This can be used to reduce the compute time of the various steps downstream of the PCA.

For CRISPR data, quality control can be performed using computeCrisprQcMetrics(), suggestCrisprQcThresholds() and filterCrisprQcMetrics(). To normalize, we use size factors defined by centering the total sum of guide counts for each cell.