Contents

0.1 Introduction

SpotSweeper is an R package for spatial transcriptomics data quality control (QC). It provides functions for detecting and visualizing spot-level local outliers and artifacts using spatially-aware methods. The package is designed to work with SpatialExperiment objects, and is compatible with data from 10X Genomics Visium and other spatial transcriptomics platforms.

0.2 Installation

Currently, the only way to install SpotSweeper is by downloading the development version which can be installed from GitHub using the following:

if (!require("devtools")) install.packages("devtools")
remotes::install_github("MicTott/SpotSweeper")

Once accepted in Bioconductor, SpotSweeper will be installable using:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}

BiocManager::install("SpotSweeper")

0.3 Spot-level local outlier detection

0.3.1 Loading example data

Here we’ll walk you through the standard workflow for using ‘SpotSweeper’ to detect and visualize local outliers in spatial transcriptomics data. We’ll use the Visium_humanDLPFC dataset from the STexampleData package, which is a SpatialExperiment object.

Because local outliers will be saved in the colData of the SpatialExperiment object, we’ll first view the colData and drop out-of-tissue spots before calculating quality control (QC) metrics and running SpotSweeper.

library(SpotSweeper)

# load  Maynard et al DLPFC daatset
spe <- STexampleData::Visium_humanDLPFC()
## see ?STexampleData and browseVignettes('STexampleData') for documentation
## loading from cache
# show column data before SpotSweeper
colnames(colData(spe))
## [1] "barcode_id"   "sample_id"    "in_tissue"    "array_row"    "array_col"   
## [6] "ground_truth" "reference"    "cell_count"
# drop out-of-tissue spots
spe <- spe[, spe$in_tissue == 1]

0.3.2 Calculating QC metrics using scuttle

We’ll use the scuttle package to calculate QC metrics. To do this, we’ll need to first change the rownames from gene id to gene names. We’ll then get the mitochondrial transcripts and calculate QC metrics for each spot using scuttle::addPerCellQCMetrics.

# change from gene id to gene names
rownames(spe) <- rowData(spe)$gene_name

# identifying the mitochondrial transcripts
is.mito <- rownames(spe)[grepl("^MT-", rownames(spe))]

# calculating QC metrics for each spot using scuttle
spe <- scuttle::addPerCellQCMetrics(spe, subsets = list(Mito = is.mito))
colnames(colData(spe))
##  [1] "barcode_id"            "sample_id"             "in_tissue"            
##  [4] "array_row"             "array_col"             "ground_truth"         
##  [7] "reference"             "cell_count"            "sum"                  
## [10] "detected"              "subsets_Mito_sum"      "subsets_Mito_detected"
## [13] "subsets_Mito_percent"  "total"

0.3.3 Identifying local outliers using SpotSweeper

We can now use SpotSweeper to identify local outliers in the spatial transcriptomics data. We’ll use the localOutliers function to detect local outliers based on the unique detected genes, total library size, and percent of the total reads that are mitochondrial. These methods assume a normal distribution, so we’ll use the log-transformed sum of the counts and the log-transformed number of detected genes. For mitochondrial percent, we’ll use the raw mitochondrial percentage.

# library size
spe <- localOutliers(spe,
    metric = "sum",
    direction = "lower",
    log = TRUE
)

# unique genes
spe <- localOutliers(spe,
    metric = "detected",
    direction = "lower",
    log = TRUE
)

# mitochondrial percent
spe <- localOutliers(spe,
    metric = "subsets_Mito_percent",
    direction = "higher",
    log = FALSE
)

The localOutlier function automatically outputs the results to the colData with the naming convention X_outliers, where X is the name of the input colData. We can then combine all outliers into a single column called local_outliers in the colData of the SpatialExperiment object.

# combine all outliers into "local_outliers" column
spe$local_outliers <- as.logical(spe$sum_outliers) |
    as.logical(spe$detected_outliers) |
    as.logical(spe$subsets_Mito_percent_outliers)

0.3.4 Visualizing local outliers

We can visualize the local outliers using the plotQC function. This function creates a scatter plot of the specified metric and highlights the local outliers in red using the escheR package. Here, we’ll visualize local outliers of library size, unique genes, mitochondrial percent, and finally, all local outliers. We’ll then arrange these plots in a grid using ggpubr::arrange.

library(escheR)
## Loading required package: ggplot2
library(ggpubr)

# library size
p1 <- plotQC(spe,
    metric = "sum_log",
    outliers = "sum_outliers", point_size = 1.1
) +
    ggtitle("Library Size")

# unique genes
p2 <- plotQC(spe,
    metric = "detected_log",
    outliers = "detected_outliers", point_size = 1.1
) +
    ggtitle("Unique Genes")

# mitochondrial percent
p3 <- plotQC(spe,
    metric = "subsets_Mito_percent",
    outliers = "subsets_Mito_percent_outliers", point_size = 1.1
) +
    ggtitle("Mitochondrial Percent")

# all local outliers
p4 <- plotQC(spe,
    metric = "sum_log",
    outliers = "local_outliers", point_size = 1.1, stroke = 0.75
) +
    ggtitle("All Local Outliers")

# plot
plot_list <- list(p1, p2, p3, p4)
ggarrange(
    plotlist = plot_list,
    ncol = 2, nrow = 2,
    common.legend = FALSE
)

0.4 Removing technical artifacts using SpotSweeper

0.4.1 Loading example data

# load in DLPFC sample with hangnail artifact
data(DLPFC_artifact)
spe <- DLPFC_artifact

# inspect colData before artifact detection
colnames(colData(spe))
##  [1] "sample_id"          "in_tissue"          "array_row"         
##  [4] "array_col"          "key"                "sum_umi"           
##  [7] "sum_gene"           "expr_chrM"          "expr_chrM_ratio"   
## [10] "ManualAnnotation"   "subject"            "region"            
## [13] "sex"                "age"                "diagnosis"         
## [16] "sample_id_complete" "count"              "sizeFactor"

0.4.2 Visualizing technical artifacts

Technical artifacts can commonly be visualized by standard QC metrics, including library size, unique genes, or mitochondrial percentage. We can first visualize the technical artifacts using the plotQC function. This function plots the Visium spots with the specified QC metric.We’ll then again arrange these plots using ggpubr::arrange.

# library size
p1 <- plotQC(spe,
    metric = "sum_umi",
    outliers = NULL, point_size = 1.1
) +
    ggtitle("Library Size")

# unique genes
p2 <- plotQC(spe,
    metric = "sum_gene",
    outliers = NULL, point_size = 1.1
) +
    ggtitle("Unique Genes")

# mitochondrial percent
p3 <- plotQC(spe,
    metric = "expr_chrM_ratio",
    outliers = NULL, point_size = 1.1
) +
    ggtitle("Mitochondrial Percent")

# plot
plot_list <- list(p1, p2, p3)
ggarrange(
    plotlist = plot_list,
    ncol = 3, nrow = 1,
    common.legend = FALSE
)