Overview
This vignette demonstrates the use of the SpatialDecon package to estimate cell abundance in spatial gene expression studies.
We’ll analyze a small GeoMx dataset from a lung tumor, looking for abundance of different immune cell types. This dataset has 30 ROIs. In each ROI, Tumor and Microenvironment segments have been profiled separately.
Data preparation
First, we load the package:
Now let’s load our example data and examine it:
The spatialdecon function takes 3 arguments of expression data:
- The normalized data.
- A matrix of expected background for all data points in the normalized data matrix.
- Optionally, either a matrix of per-data-point weights, or the raw data, which is used to derive weights (low counts are less statistically stable, and this allows spatialdecon to down-weight them.)
We estimate each data point’s expected background from the negative control probes from its corresponding observation:
A note for background estimation: in studies with two probesets, the genes from each probeset will have distinct background values, and the above code should be run separately for each probeset using its corresponding NegProbe value. Alternatively, the “derive_GeoMx_background” can do this automatically:
Cell profile matrices
A “cell profile matrix” is a pre-defined matrix that specifies the expected expression profiles of each cell type in the experiment. The SpatialDecon library comes with one such matrix pre-loaded, the “SafeTME” matrix, designed for estimation of immune and stroma cells in the tumor microenvironment. (This matrix was designed to avoid genes commonly expressed by cancer cells; see the SpatialDecon manuscript for details.)
Let’s take a glance at the safeTME matrix:
data("safeTME")
data("safeTME.matches")
signif(safeTME[seq_len(3), seq_len(3)], 2)
#> macrophages mast B.naive
#> A2M 0.8500 0.044 0.0043
#> ABCB1 0.0021 0.023 0.0250
#> ABCB4 0.0044 0.000 0.2200
heatmap(sweep(safeTME, 1, apply(safeTME, 1, max), "/"),
labRow = NA, margins = c(10, 5))
For studies of other tissue types, we have provided a library of cell profile matrices, available on Github and downloadable with the “download_profile_matrix” function.
For a complete list of matrices, see ?download_profile_matrix.
Below we download a matrix of cell profiles derived from scRNA-seq of a mouse brain.
Using the advanced settings of spatialdecon
spatialdecon has several abilities beyond basic deconvolution:
- If given the nuclei counts for each region/observation, it returns results on the scale of total cell counts.
- If given the identities of pure tumor regions/observations, it infers a handful of tumor-specific expression profiles and appends them to the cell profile matrix. Doing this accounts for cancer cell-derived expression from any genes in the cell profile matrix, removing contaminating signal from cancer cells.
- If given raw count data, it derives per-data-point weights, using an error model derived for GeoMx data.
- If given a “cellmatches” argument, it sums multiple closely-related cell types into a single score. E.g. if the safeTME matrix is used with the cell-matching data object “safeTME.matches”, it e.g. sums the “T.CD8.naive” and “T.CD8.memory” scores into a single “CD8.T.cells” score.
Let’s take a look at an example cell matching object:
Now let’s run spatialdecon:
# vector identifying pure tumor segments:
annot$istumor = (annot$AOI.name == "Tumor")
# run spatialdecon with all the bells and whistles:
restils = spatialdecon(norm = norm, # normalized data
raw = raw, # raw data, used to down-weight low-count observations
bg = bg, # expected background counts for every data point in norm
X = safeTME, # safeTME matrix, used by default
cellmerges = safeTME.matches, # safeTME.matches object, used by default
cell_counts = annot$nuclei, # nuclei counts, used to estimate total cells
is_pure_tumor = annot$istumor, # identities of the Tumor segments/observations
n_tumor_clusters = 5) # how many distinct tumor profiles to append to safeTME
str(restils)
#> List of 13
#> $ beta : num [1:14, 1:30] 3.64744 0.33137 0.00437 0.00252 0.38872 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ yhat : num [1:544, 1:30] 25.42 2.45 20.4 1.55 2.4 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:544] "A2M" "ABCB1" "ACP5" "ADAM12" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ resids : num [1:544, 1:30] -0.565 -0.261 0.352 -0.278 0.35 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:544] "A2M" "ABCB1" "ACP5" "ADAM12" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ p : num [1:14, 1:30] 3.17e-05 5.07e-03 9.86e-01 9.86e-01 7.78e-01 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ t : num [1:14, 1:30] 4.198 2.8143 0.0172 0.0174 0.2815 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ se : num [1:14, 1:30] 0.869 0.118 0.254 0.145 1.381 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ beta.granular : num [1:23, 1:30] 3.64744 0.33137 0.00437 0 0.00252 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:23] "macrophages" "mast" "B.naive" "B.memory" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ sigma.granular : num [1:23, 1:23, 1:30] 0.75492 -0.003 0.00476 -0.00196 -0.00133 ...
#> ..- attr(*, "dimnames")=List of 3
#> .. ..$ : chr [1:23] "macrophages" "mast" "B.naive" "B.memory" ...
#> .. ..$ : chr [1:23] "macrophages" "mast" "B.naive" "B.memory" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ sigma : num [1:14, 1:14, 1:30] 0.75492 -0.003 0.00281 -0.00133 0.06478 ...
#> ..- attr(*, "dimnames")=List of 3
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ prop_of_all : num [1:14, 1:30] 0.504836 0.045864 0.000605 0.000349 0.053802 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ prop_of_nontumor: num [1:14, 1:30] 0.504836 0.045864 0.000605 0.000349 0.053802 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ cell.counts :List of 2
#> ..$ cells.per.100: num [1:14, 1:30] 18.8784 1.7151 0.0226 0.013 2.0119 ...
#> .. ..- attr(*, "dimnames")=List of 2
#> .. .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> ..$ cell.counts : num [1:14, 1:30] 165.942 15.076 0.199 0.115 17.685 ...
#> .. ..- attr(*, "dimnames")=List of 2
#> .. .. ..$ : chr [1:14] "macrophages" "mast" "B" "plasma" ...
#> .. .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ X : num [1:544, 1:23] 0.85357 0.00213 3.5616 0.01582 0.13006 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:544] "A2M" "ABCB1" "ACP5" "ADAM12" ...
#> .. ..$ : chr [1:23] "macrophages" "mast" "B.naive" "B.memory" ...
There are quite a few readouts here. Let’s review the important ones:
- beta: the cell abundance scores of the rolled-up/major cell types
- beta.granular: the cell abundance scores of the granular cell types, corresponding to the columns of the cell profile matrix
- yhat, resids: the fitted values and log2-scale residuals from the deconvolution fit. Can be used to measure each observation’s goodness-of-fit, a possible QC metric.
- cell.counts, cell.counts.granular: estimated numbers of each cell type, derived using the nuclei count input
- prop_of_nontumor: the beta matrix rescaled to give the proportions of non-tumor cells in each observation.
- X: the cell profile matrix used, including newly-derived tumor-specific columns.
To illustrate the derivation of tumor profiles, let’s look at the cell profile matrix output by spatialdecon:
Note the new tumor-specific columns.
Finally, let’s compare deconvolution results from basic vs. the advanced setting with tumor profiles appended (just for a few cell types):
par(mfrow = c(2, 3))
par(mar = c(5,7,2,1))
for (i in seq_len(6)) {
cell = rownames(res$beta)[i]
plot(res$beta[cell, ], restils$beta.granular[cell, ],
xlab = paste0(cell, " score under basic setting"),
ylab = paste0(cell, " score when tumor\ncells are modelled"),
pch = 16,
col = c(rgb(0,0,1,0.5), rgb(1,0,0,0.5))[1 + annot$istumor],
xlim = range(c(res$beta[cell, ], restils$beta.granular[cell, ])),
ylim = range(c(res$beta[cell, ], restils$beta.granular[cell, ])))
abline(0,1)
if (i == 1) {
legend("topleft", pch = 16, col = c(rgb(0,0,1,0.5), rgb(1,0,0,0.5)),
legend = c("microenv.", "tumor"))
}
}
So the impact of modelling tumor is two-fold:
- Estimated immune cell content in tumor segments is driven down all the way, or almost all the way, to 0.
- Estimated immune cell abundance in microenvironment segments in suppressed, as part of the gene expression is attributed to cancer cells instead of immune cells.
Plotting deconvolution results
The SpatialDecon package contains two specialized plotting functions, and a default color palette for the safeTME matrix.
The first function is “TIL_barplot”, which is just a convenient way of drawing barplots of cell type abundance.
The second function is “florets”, used for plotting cell abundances atop some 2-D projection. Here, we’ll plot cell abundances atop the first 2 principal components of the data:
# PCA of the normalized data:
pc = prcomp(t(log2(pmax(norm, 1))))$x[, c(1, 2)]
# run florets function:
par(mar = c(5,5,1,1))
layout(mat = (matrix(c(1, 2), 1)), widths = c(6, 2))
florets(x = pc[, 1], y = pc[, 2],
b = restils$beta, cex = 2,
xlab = "PC1", ylab = "PC2")
par(mar = c(0,0,0,0))
frame()
legend("center", fill = cellcols[rownames(restils$beta)],
legend = rownames(restils$beta), cex = 0.7)
So we can see that PC1 roughly tracks many vs. few immune cells, and PC2 tracks the relative abundance of lymphoid/myeloid populations.
Other functions
The SpatialDecon library includes several helpful functions for further analysis/fine-tuning of deconvolution results.
Combining cell types:
When two cell types are too similar, the estimation of their abundances becomes unstable. However, their sum can still be estimated easily. The function “collapseCellTypes” takes a deconvolution results object and collapses any colsely-related cell types you tell it to:
Inferring an expression profile for a cell type omitted from the profile matrix
Sometimes a cell profile matrix will omit a cell type you know to be present in a tissue. If your data includes any regions that are purely this unmodelled cell type - e.g. because you’ve used the GeoMx platform’s segmentation capability to specifically select them - then you can infer a profile for that cell type and merge it with your cell profile matrix. The algorithm clusters all the observations you designate as purely the unmodelled cell type, and collapses those clusters into as many profiles of that cell type as you wish. For cancer cell, it may be appropriate to specify 10 or more clusters; for highly regular healthy cells, one cluster may suffice.
(Note: this functionality can also be run within the spatialdecon function, as is demonstrated further above.)
pure.tumor.ids = annot$AOI.name == "Tumor"
safeTME.with.tumor = mergeTumorIntoX(norm = norm,
bg = bg,
pure_tumor_ids = pure.tumor.ids,
X = safeTME,
K = 3)
heatmap(sweep(safeTME.with.tumor, 1, apply(safeTME.with.tumor, 1, max), "/"),
labRow = NA, margins = c(10, 5))
Reverse deconvolution
Once cell type abundance has been estimated, we can flip the deconvolution around, modelling the expression data as a function of cell abundances, and thereby deriving:
- Estimated expression of each gene in each cell type. (Including for genes not present in your cell profile matrix)
- Fitted expression values for each gene based on cell mixing.
- Residuals of each gene: how does their expression compare to what cell mixing would predict?
- Two metrics of how well genes are predicted by/ redundant with cell mixing: correlation between observed and fitted expression, and residual SD.
The function “reversedecon” runs this model.
rdecon = reverseDecon(norm = norm,
beta = res$beta)
str(rdecon)
#> List of 5
#> $ coefs : num [1:545, 1:19] 1.442 1.312 0 0.683 0.975 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:545] "A2M" "ABCB1" "ACP5" "ADAM12" ...
#> .. ..$ : chr [1:19] "(Intercept)" "macrophages" "mast" "B.naive" ...
#> $ yhat : num [1:545, 1:30] 17.47 2.44 32.4 1.11 2.86 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:545] "A2M" "ABCB1" "ACP5" "ADAM12" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ resids : num [1:545, 1:30] -0.0233 -0.2571 -0.316 0.2014 0.0979 ...
#> ..- attr(*, "dimnames")=List of 2
#> .. ..$ : chr [1:545] "A2M" "ABCB1" "ACP5" "ADAM12" ...
#> .. ..$ : chr [1:30] "ROI10TME" "ROI10Tumor" "ROI11TME" "ROI11Tumor" ...
#> $ cors : Named num [1:545] 0.869 0.552 0.961 0.916 0.909 ...
#> ..- attr(*, "names")= chr [1:545] "A2M" "ABCB1" "ACP5" "ADAM12" ...
#> $ resid.sd: Named num [1:545] 0.364 0.233 0.386 0.329 0.196 ...
#> ..- attr(*, "names")= chr [1:545] "A2M" "ABCB1" "ACP5" "ADAM12" ...
# look at the residuals:
heatmap(pmax(pmin(rdecon$resids, 2), -2))
# look at the two metrics of goodness-of-fit:
plot(rdecon$cors, rdecon$resid.sd, col = 0)
showgenes = c("CXCL14", "LYZ", "NKG7")
text(rdecon$cors[setdiff(names(rdecon$cors), showgenes)],
rdecon$resid.sd[setdiff(names(rdecon$cors), showgenes)],
setdiff(names(rdecon$cors), showgenes), cex = 0.5)
text(rdecon$cors[showgenes], rdecon$resid.sd[showgenes],
showgenes, cex = 0.75, col = 2)
From the above plot, we can see that genes like CXCL14 vary independently of cell mixing, genes like LYZ are correlated with cell mixing but still have variable expression, and genes like NKG7 serve as nothing but obtuse readouts of cell mixing.
