SpaTopic Basics

Xiyu Peng

2025-02-27

**More detailed documentation is available at the SpaTopic Home Page. Please check the github page for more detailed information for the package.

Introduction

Recent advancements in multiplexed tissue imaging allow for examination of tissue microenvironments in great detail. These cutting-edge technologies offer invaluable insights into cellular heterogeneity and spatial architectures, playing a crucial role in decoding mechanisms of treatment response and disease progression.

However, gaining a deep understanding of complex spatial patterns remains challenging. SpaTopic implements a novel spatial topic model to integrate both cell type and spatial information to identify the complex spatial tissue structures without human intervention. The Collapsed Gibbs sampling algorithm is used for model inference. Contrasting to computationally intensive K-nearest-neighbor-based cell neighborhood analysis approaches, SpaTopic is more scalable to large-scale image datasets without extracting neighborhood information for every single cell.

SpaTopic can be applied either on a single image or across multiple images.

Simple Usage

The required input of SpaTopic is a data frame containing cells within on a single image or a list of data frames for multiple images. Each data frame consists of four columns:

library(SpaTopic)
packageVersion("SpaTopic")
#> [1] '1.2.0'
library(sf)
## The input can be a data frame or a list of data frames
data("lung5")
head(lung5)
#>      image        X        Y           type
#> 1_1 image1 4215.889 158847.7      Dendritic
#> 2_1 image1 6092.889 158834.7     Macrophage
#> 3_1 image1 7214.889 158843.7 Neuroendocrine
#> 4_1 image1 7418.889 158813.7     Macrophage
#> 5_1 image1 7446.889 158845.7     Macrophage
#> 6_1 image1 3254.889 158838.7          CD4 T

Run Gibbs Sampling

## Gibbs sampling
gibbs.res<-SpaTopic_inference(lung5, ntopics = 7, sigma = 50, region_radius = 400)

Check the output of SpaTopic

print(gibbs.res)
#> SpaTopic Results
#> ----------------
#> Number of topics: 7 
#> Perplexity: 11.31563 
#> 
#> Topic Content(Topic distribution across cell types):
#>                                 topic1       topic2       topic3      topic4
#> Alveolar Epithelial Type 1 0.035870295 6.511503e-03 4.541367e-06 0.026643327
#> Alveolar Epithelial Type 2 0.025386476 3.553900e-02 4.541367e-06 0.017427665
#> Artery                     0.007545591 2.624548e-06 9.128148e-04 0.001856373
#> B                          0.018581190 5.800251e-04 3.446035e-01 0.015203195
#> Basal                      0.025846292 7.753466e-01 1.730261e-03 0.089193312
#>                                  topic5       topic6      topic7
#> Alveolar Epithelial Type 1 2.987411e-06 6.348481e-06 0.005341969
#> Alveolar Epithelial Type 2 2.987411e-06 6.348481e-06 0.006994451
#> Artery                     5.320579e-03 2.044846e-02 0.006041096
#> B                          1.912242e-02 3.434528e-03 0.018434717
#> Basal                      4.902342e-03 6.348481e-06 0.006549552
#> ...
#> 
#> Use $Z.trace for posterior probabilities of topic assignments for each cell
#> Use $cell_topics for final topic assignments for each cell
#> Use $parameters for accessing model parameters

For more detailed usage of SpaTopic and how to interprete output from SpaTopic, please check the complete tutorial in SpaTopic Home Page. We also provide a function to prepare input from Seurat v5 object.