SpaTalk: Quick Start Guide

Introduction

SpaTalk is a computational framework for inferring spatially resolved cell-cell communications (CCIs) from spatial transcriptomics (ST) data. Published in Nature Communications (2022), SpaTalk integrates graph network modeling and knowledge graph approaches to reconstruct ligand-receptor-target signaling networks between spatially proximal cells.

Citation

Shao, X., Li, C., Yang, H., et al. Knowledge-graph-based cell-cell communication inference for spatially resolved transcriptomic data with SpaTalk. Nature Communications 13, 4429 (2022). https://doi.org/10.1038/s41467-022-32111-8

Key Features

Cell-type deconvolution for spot-based ST data using NNLM
Spatial mapping between scRNA-seq and ST data
Knowledge graph-based ligand-receptor-target pathway inference
Permutation-based statistical validation
Support for single-cell and spot-based ST platforms

Installation

# From R-universe (recommended)
install.packages("SpaTalk", repos = "https://zaoqu-liu.r-universe.dev")

# From GitHub
devtools::install_github("Zaoqu-Liu/SpaTalk")

Quick Start with STARmap Data

This tutorial uses the built-in STARmap mouse visual cortex data.

Step 1: Load Package and Data

library(SpaTalk)

# Load built-in demo data
load(system.file("extdata", "starmap_data.rda", package = "SpaTalk"))
load(system.file("extdata", "starmap_meta.rda", package = "SpaTalk"))

# Load curated databases
data(lrpairs)
data(pathways)

cat("Expression matrix:", nrow(starmap_data), "genes x", ncol(starmap_data), "cells\n")
#> Expression matrix: 996 genes x 930 cells
cat("Metadata:", nrow(starmap_meta), "cells\n")
#> Metadata: 930 cells
cat("Cell types:", paste(unique(starmap_meta$celltype), collapse = ", "), "\n")
#> Cell types: eL2_3, eL6, Astro, PVALB, Endo, VIP, SST, Smc, eL4, Micro, Oligo, eL5, Reln, HPC

Step 2: Create SpaTalk Object

# Prepare spatial metadata
st_meta <- data.frame(
  cell = starmap_meta$cell,
  x = starmap_meta$x,
  y = starmap_meta$y
)

# Create SpaTalk object (single-cell resolution data)
obj <- createSpaTalk(
  st_data = starmap_data,
  st_meta = st_meta,
  species = "Mouse",
  if_st_is_sc = TRUE,
  spot_max_cell = 1,
  celltype = starmap_meta$celltype
)

obj
#> An object of class SpaTalk 
#> 996 genes across 930 single-cells (0 lrpair)

Step 3: Visualize Spatial Distribution

plot_st_celltype_all(obj, size = 1.2)

Spatial distribution of all cell types

Step 4: Filter LR-Pathway Pairs

# Find LR pairs with downstream pathway targets
obj <- find_lr_path(
  object = obj,
  lrpairs = lrpairs,
  pathways = pathways,
  if_doParallel = FALSE
)
#> Checking input data 
#> Begin to filter lrpairs and pathways 
#> ***Done***

cat("Filtered LR pairs:", nrow(obj@lr_path$lrpairs), "\n")
#> Filtered LR pairs: 6

Step 5: Infer Cell-Cell Communications

# Infer CCIs between specific cell types
obj <- dec_cci(
  object = obj,
  celltype_sender = "eL6",
  celltype_receiver = "PVALB",
  if_doParallel = FALSE
)
#> Begin to find LR pairs

# View results
if(nrow(obj@lrpair) > 0) {
  cat("Found", nrow(obj@lrpair), "significant LR pairs:\n")
  print(obj@lrpair[, c("ligand", "receptor", "lr_co_ratio", "lr_co_ratio_pvalue", "score")])
}
#> Found 1 significant LR pairs:
#>   ligand receptor lr_co_ratio lr_co_ratio_pvalue     score
#> 5  Inhba   Acvr1c   0.1666667                  0 0.8550196

Step 6: Visualize Results

Cell-Cell Distance Distribution

plot_ccdist(
  object = obj,
  celltype_sender = "eL6",
  celltype_receiver = "PVALB"
)

Distance distribution between eL6 and PVALB cells

LR Pair Spatial Distribution

if(nrow(obj@lrpair) > 0) {
  lr <- obj@lrpair[1, ]
  plot_lrpair(
    object = obj,
    ligand = lr$ligand,
    receptor = lr$receptor,
    celltype_sender = "eL6",
    celltype_receiver = "PVALB",
    size = 1.2
  )
}

Spatial distribution of ligand-receptor interactions

Next Steps

See the Algorithm vignette for methodological details
See the Visualization vignette for all plotting options
See the Advanced Usage vignette for custom databases and parallel processing
See the Platforms vignette for platform-specific workflows

Session Info

sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] parallel  stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#> [1] SpaTalk_2.0.0     doParallel_1.0.17 iterators_1.0.14  foreach_1.5.2    
#> [5] ggalluvial_0.12.6 ggplot2_4.0.3     rmarkdown_2.31   
#> 
#> loaded via a namespace (and not attached):
#>   [1] RColorBrewer_1.1-3     sys_3.4.3              jsonlite_2.0.0        
#>   [4] magrittr_2.0.5         spatstat.utils_3.2-3   farver_2.1.2          
#>   [7] fs_2.1.0               vctrs_0.7.3            ROCR_1.0-12           
#>  [10] spatstat.explore_3.8-1 rstatix_0.7.3          htmltools_0.5.9       
#>  [13] progress_1.2.3         broom_1.0.13           Formula_1.2-5         
#>  [16] sass_0.4.10            sctransform_0.4.3      parallelly_1.48.0     
#>  [19] KernSmooth_2.23-26     bslib_0.11.0           htmlwidgets_1.6.4     
#>  [22] ica_1.0-3              plyr_1.8.9             plotly_4.12.0         
#>  [25] zoo_1.8-15             cachem_1.1.0           buildtools_1.0.0      
#>  [28] igraph_2.3.3           mime_0.13              lifecycle_1.0.5       
#>  [31] pkgconfig_2.0.3        Matrix_1.7-5           R6_2.6.1              
#>  [34] fastmap_1.2.0          fitdistrplus_1.2-6     future_1.70.0         
#>  [37] shiny_1.14.0           digest_0.6.39          patchwork_1.3.2       
#>  [40] Seurat_5.5.1           tensor_1.5.1           RSpectra_0.16-2       
#>  [43] irlba_2.3.7            ggpubr_0.6.3           labeling_0.4.3        
#>  [46] progressr_0.19.0       spatstat.sparse_3.2-0  httr_1.4.8            
#>  [49] polyclip_1.10-7        abind_1.4-8            compiler_4.6.1        
#>  [52] withr_3.0.3            backports_1.5.1        S7_0.2.2              
#>  [55] carData_3.0-6          fastDummies_1.7.6      ggforce_0.5.0         
#>  [58] ggsignif_0.6.4         MASS_7.3-65            rappdirs_0.3.4        
#>  [61] ggsci_5.1.0            tools_4.6.1            lmtest_0.9-40         
#>  [64] otel_0.2.0             scatterpie_0.2.6       httpuv_1.6.17         
#>  [67] future.apply_1.20.2    goftest_1.2-3          glue_1.8.1            
#>  [70] nlme_3.1-169           promises_1.5.0         grid_4.6.1            
#>  [73] Rtsne_0.17             cluster_2.1.8.2        reshape2_1.4.5        
#>  [76] generics_0.1.4         gtable_0.3.6           spatstat.data_3.1-9   
#>  [79] tzdb_0.5.0             tidyr_1.3.2            data.table_1.18.4     
#>  [82] hms_1.1.4              car_3.1-5              sp_2.2-1              
#>  [85] spatstat.geom_3.8-1    RcppAnnoy_0.0.23       ggrepel_0.9.8         
#>  [88] RANN_2.6.2             pillar_1.11.1          stringr_1.6.0         
#>  [91] yulab.utils_0.2.4      ggExtra_0.11.0         spam_2.11-4           
#>  [94] RcppHNSW_0.7.0         later_1.4.8            splines_4.6.1         
#>  [97] tweenr_2.0.3           dplyr_1.2.1            lattice_0.22-9        
#> [100] survival_3.8-6         deldir_2.0-4           tidyselect_1.2.1      
#> [103] maketools_1.3.2        miniUI_0.1.2           pbapply_1.7-4         
#> [106] knitr_1.51             gridExtra_2.3.1        scattermore_1.2       
#> [109] xfun_0.59              matrixStats_1.5.0      pheatmap_1.0.13       
#> [112] stringi_1.8.7          ggfun_0.2.1            lazyeval_0.2.3        
#> [115] yaml_2.3.12            evaluate_1.0.5         codetools_0.2-20      
#> [118] tibble_3.3.1           cli_3.6.6              uwot_0.2.4            
#> [121] xtable_1.8-8           reticulate_1.46.0      jquerylib_0.1.4       
#> [124] Rcpp_1.1.1-1.1         globals_0.19.1         spatstat.random_3.5-0 
#> [127] png_0.1-9              spatstat.univar_3.2-0  readr_2.2.0           
#> [130] prettyunits_1.2.0      dotCall64_1.2          listenv_1.0.0         
#> [133] viridisLite_0.4.3      scales_1.4.0           ggridges_0.5.7        
#> [136] SeuratObject_5.4.0     purrr_1.2.2            crayon_1.5.3          
#> [139] rlang_1.2.0            cowplot_1.2.0