Imaging-based Spatial Transcriptomics Data Quality Control with SpaceTrooper

Load example data

SpaceTrooper provides three different reading functions, one per each technology, that load data into a SpatialExperiment object. For more details on how to correctly specify the inputs, please refer to the SpaceTrooper utilities vignette.

library(SpaceTrooper)
library(ggplot2)

cosmxFolder <- system.file(file.path("extdata", "CosMx_DBKero_Tiny"), 
                        package="SpaceTrooper")
spe <- readCosmxSPE(cosmxFolder, sampleName="DBKero_CosMx")

spe

## class: SpatialExperiment 
## dim: 1010 905 
## metadata(4): fov_positions fov_dim polygons technology
## assays(1): counts
## rownames(1010): RAMP2 CD83 ... NegPrb09 NegPrb10
## rowData names(0):
## colnames(905): f16_c1 f16_c10 ... f16_c98 f16_c99
## colData names(20): fov cellID ... sample_id cell_id
## reducedDimNames(0):
## mainExpName: NULL
## altExpNames(0):
## spatialCoords names(2) : CenterX_global_px CenterY_global_px
## imgData names(1): sample_id

In addition, we provide the code for loading Xenium, and MERFISH example data. Please, note that for these technologies the parameters are configured to automatically load polygons and compute missing metrics, so these steps don’t need to be run again. To proceed with these technologies, skip directly to Add QC metrics.

xeniumFolder <- system.file( "extdata", "Xenium_small", package="SpaceTrooper")
xen <- readXeniumSPE(xeniumFolder, computeMissingMetrics=TRUE,
                        keepPolygons=TRUE)

merfishFolder <- system.file("extdata", "Merfish_Tiny", package="SpaceTrooper")
mer <- readMerfishSPE(merfishFolder, boundariesType="parquet",
                        computeMissingMetrics=TRUE, keepPolygons=TRUE)

Field of View (FOVs) visualization

In this section, we show how to plot each cell position onto the map of the Fields of View (FOVs), whose coordinates are provided only for CosMx technology.

IMPORTANT: we have noticed that according to CosMx version, there could be a misalignment of FOVs and cell centroids, that can be easily corrected with a single line of code. Therefore, it is crucial to generate this plot to check for any spatial shift, as such misalignment directly affects the QS computation.

# to check misalignment
plotCellsFovs(spe, size = 3, alpha = 0.7)

The dataset is a subset with just a single FoV, whose number is displayed at the center. Cell centroids, shown in dark red, are all contained by FoV boundaries, thus no shift correction is needed here.

When an experiment has multiple FoVs, you can see the map and the topological organization of the FoVs, together with their numbers.

If any misalignment is observed, it can be corrected by adjusting the FoV coordinates directly. For instance, if the FoVs are shifted upward by one FoV height (which, for CosMx technology, corresponds to 4,256 pixels), you can correct this by subtracting that value from the FoVs y coordinates:

# code line for shift correction
# metadata(spe)$fov_positions$y_global_px <- metadata(spe)$fov_positions$y_global_px - 4256

Load polygons

In this section we show how to load polygons after SpatialExperiment creation, only for visualization purposes. They are stored as an sf object within colData.

This step is not mandatory for CosMx, because the pipeline can be executed even without them.

# polygon loading
spe <- readAndAddPolygonsToSPE(spe, boundariesType="csv")

Please pay attention to any warnings. Cell polygons with fewer than four vertices cannot be handled by the geometry packages used by SpaceTrooper. Therefore, the corresponding cells are discarded from the SpatialExperiment object.

Add QC metrics

The following sections will work the same way for all types of data.

The spatialPerCellQC function computes additional metrics per each cell, that are saved inside the SpatialExperimentand accessible through colData(spe). It is mandatory to run this function before computing QS.

The negProbList parameter is, by default, a vector containing all control probe patterns encountered so far across the supported technologies. Because these patterns continue to evolve, some may not yet be included. If you find that your control probe patterns are missing from the default list, you can define a custom vector, as shown below.

By default, the function automatically removes 0 count cells, but this can be handled with the rmZeros parameter.

spe <- spatialPerCellQC(spe, rmZeros=TRUE,
        negProbList=c("NegPrb", "Negative", "SystemControl"))

## Removing 1 cells with 0 counts!

colnames(colData(spe))

##  [1] "fov"                     "cellID"                 
##  [3] "Area"                    "AspectRatio"            
##  [5] "CenterX_local_px"        "CenterY_local_px"       
##  [7] "Width"                   "Height"                 
##  [9] "Mean.PanCK"              "Max.PanCK"              
## [11] "Mean.CD68"               "Max.CD68"               
## [13] "Mean.MembraneStain_B2M"  "Max.MembraneStain_B2M"  
## [15] "Mean.CD45"               "Max.CD45"               
## [17] "Mean.DAPI"               "Max.DAPI"               
## [19] "sample_id"               "cell_id"                
## [21] "polygons"                "sum"                    
## [23] "detected"                "subsets_NegPrb_sum"     
## [25] "subsets_NegPrb_detected" "subsets_NegPrb_percent" 
## [27] "total"                   "control_sum"            
## [29] "control_detected"        "target_sum"             
## [31] "target_detected"         "CenterX_global_px"      
## [33] "CenterY_global_px"       "ctrl_total_ratio"       
## [35] "log2Ctrl_total_ratio"    "CenterX_global_um"      
## [37] "CenterY_global_um"       "Area_um"                
## [39] "dist_border_x"           "dist_border_y"          
## [41] "dist_border"             "log2AspectRatio"        
## [43] "SignalDensity"           "log2SignalDensity"

Several metrics are added, both derived from expression assay and cell morphology. Some of them are directly used to compute QS:

• log2SignalDensity: log2-transformed ratio between total probe counts per cell and cell area in µm² (or volume in µm³ for MERFISH technology);
• Area_um: cell area in µm² (or volume in µm³ in the case of MERFISH technology);
• log2Ctrl_total_ratio: log2-transformed ratio between total negative control probe counts and total probe count per cell;
• log2AspectRatio: log2-transformed ratio between cell maximum length along the x dimension and cell maximum length along the y dimension (pixels). This metric is taken in absolute value and combined with dist_border to consider only cells within 50 pixels from the nearest FoV border (only for CosMx technology).

For a better detailed explanation of the other metrics, please refer to the SpaceTrooper utilities vignette.

Compute Quality Score

computeQCScore function calculates QS per each cell. QS combines several metrics into a formula: log2SignalDensity, corresponding to signal density, Area_um or volume, i.e. cell size, log2Ctrl_total_ratio, namely background signal and log2AspectRatio combined with dist_border, which jointly correspond to the border effect (only for CosMx technology).

glmnet package is used to estimate the coefficients of the formula, resulting in a robust score that captures low-quality cells. During model training, the selected cells are used as good or bad examples to learn how each term in the formula contributes to cell quality.

IMPORTANT: please, pay attention to any warning. If a term has too few bad examples (fewer than 0.1% of the total number of cells), it is excluded from the formula and therefore not used in the QS computation.

The QS (stored as QC_score in coldata) ranges from 0 to 1, with 0 meaning low-quality and 1 high-quality.

We are setting a seed to ensure reproducibility in this tutorial, because there are stochastic processes underlying QS computation.

set.seed(1713)

spe <- computeQCScore(spe)

summary(spe$QC_score)

##     Min.  1st Qu.   Median     Mean  3rd Qu.     Max. 
## 0.003429 0.786016 0.883948 0.798579 0.936674 0.988138

In this case, all the terms were used as no warning appeared.

Subsequently, it is possible also to assess which cells have a QS lower than a certain threshold (default is 0.5) with the following function. It creates a new column called low_qcscore inside of colData.

spe <- computeQCScoreFlags(spe, qsThreshold=0.5)

table(spe$low_qcscore)

## 
## FALSE  TRUE 
##   807    97

Using this threshold, 97 cells are flagged as low-quality. We do not suggest a fixed default threshold, but it is advisable to check the QS distribution before setting any threshold.

Data visualization

SpaceTrooper comes with several functions to view cells and metrics.

To view the distribution of whatever quantitative metric, plotMetricHist comes in handy.

# view quantitative metric distribution
plotMetricHist(spe, metric = "QC_score")

The QS distribution exhibits a left tail starting around 0.75.

Cell visualization can be obtained by using either centroids (recommended when the dataset has a large number of cells) or polygons.

plotCentroids plots cell centroids that can be colored by a certain metric contained in the colData slot, by using the colour_by parameter.

Additionally, if you have a palette column in colData, containing colors for each cell, it can be given to palette parameter, so that it automatically matches the column passed in colour_by. As an example, we are using the cell types obtained as described in the paper with their own color palette.

labf <- system.file(file.path("extdata", "CosMx_DBKero_Tiny",
                            "labels_tiny.tsv"), package="SpaceTrooper")
labs <- read.table(file=labf, sep="\t", header=TRUE)

spe$labels <- as.factor(labs[match(spe$cell_id, labs$cell_id),]$label)
spe$labels_colors <- as.factor(labs[match(spe$cell_id, labs$cell_id),]$lab_color)

plotCentroids(spe, colourBy="labels", size=3, palette="labels_colors")

Cell centroids colored by cell types allow to view the spatial distribution of cell populations in the sample.

When possible, polygon visualization gives a better overview of the cells’ spatial organization and morphological characteristics. Polygons are stored as an sf object within colData, so they can be viewed using standard ggplot2 functions. For CosMx technology, the polygons must be explicitly loaded as described in Load polygons. SpaceTrooper provides plotPolygons function that works just like plotCentroids but takes polygons instead of centroids.

plotPolygons(spe, colourBy="log2SignalDensity")

plotPolygons(spe, colourBy="Area_um")

plotPolygons(spe, colourBy="log2Ctrl_total_ratio")

plotPolygons(spe, colourBy="log2AspectRatio")

We can see in yellow and darkviolet that there are few cells with extreme values of either log2SignalDensity, Area_um, log2Ctrl_total_ratio and log2AspectRatio.

Since all plotting functions are based on ggplot2, you can easily customize the graphical outputs by adding standard ggplot2 components.

plotPolygons(spe, colourBy="QC_score") + 
    scale_fill_viridis_c(option = "plasma")

We can see that the QS is able to detect both the aspects highlighted by log2SignalDensity,Area_um, log2Ctrl_total_ratio or log2AspectRatio. Cells that showed either lower signal density, bigger size, higher background signal or border effect also display low QS (darker color).

It’s up to the user to choose an appropriate threshold to flag cells according to the observed QS distribution.

plotPolygons(spe, colourBy="low_qcscore") + 
    scale_fill_manual(values=c("TRUE"="red", "FALSE" = "#c0c8cf"))

You can reruncomputeQCScoreFlags to check how many cells would be flagged using another threshold.

spe <- computeQCScoreFlags(spe, qsThreshold=0.75)

table(spe$low_qcscore)

## 
## FALSE  TRUE 
##   711   193

Using this threshold, 193 cells are flagged as low-quality.

plotPolygons(spe, colourBy="low_qcscore") + 
    scale_fill_manual(values=c("TRUE"="red", "FALSE" = "#c0c8cf"))

The threshold is more stringent and more cells are flagged compared to the previous one. It’s up to you to choose a threshold that better suits your analysis needs.