STDistance - Spatial Transcriptomics Distance Calculation and Visualization

In STDistance: Spatial Transcriptomics Distance Calculation and Visualization

Description

STDistance is an R package designed for analyzing spatial relationships between cell types in spatial transcriptomics data. It calculates nearest neighbor distances between specified cell types and provides comprehensive visualization tools to explore spatial patterns. The package is particularly useful for studying cell-cell interactions, immune microenvironment characterization, and spatial organization of tissues.

Key features include:

• Distance calculation between reference and target cell types
• Boxplot visualization of distance distributions
• Radial network visualization of spatial relationships
• Spatial mapping of cell type interactions
• Correlation analysis between gene expression and spatial distances

Installation

# Install from CRAN
install.packages("STDistance")

# Or install the development version from GitHub:
# install.packages("devtools")
library(devtools)
devtools::install_github("PrinceWang2018/ST_Distance")

Dependencies

STDistance requires R (≥ 4.0.0) and depends on the following packages:

• dplyr
• ggplot2
• Hmisc
• scales
• stats
• RColorBrewer
• tidyr

Input File Preparation

STDistance requires two input files:

1. Spatial coordinates file (e.g., tissue_positions.csv):

2. Should contain spatial coordinates of spots/cells

3. Must include columns for barcode, x and y coordinates

4. For multiple samples, include "Sample" and "Newbarcode" columns

5. Example format:

   barcode,in_tissue,array_row,array_col,pxl_row_in_fullres,pxl_col_in_fullres ,Sample,Sampleid,Newbarcode AAACCCAAGGCTTTCA-1_1,1,50,102,4950,10020,Sample1,1,AAACCCAAGGCTTTCA-1_1

6. Metadata file (e.g., metadata.csv):

7. Should contain cell type annotations and any expression metrics

8. Must include: orig.ident, celltype columns

9. The first colume must match the barcode/newbarcode column in tissue_positions.csv

10. May include gene expression or splicing index values

11. Example format:

    ,orig.ident,nCount_Spatial,nFeature_Spatial,nCount_SCT,nFeature_SCT, integrated_snn_res.0.8,seurat_clusters,celltype_ABCDepi,gen2_SPLIz_numeric AAATCGTGTACCACAA-1_6,SP6,5403,2647,6486,2601,5,5,Epithelial_cells_B,0.96565309 AACCCTACTGTCAATA-1_6,SP6,40683,8876,8578,4328,4,4,Epithelial_cells_A,-0.300446291

12. Can be exported from Seurat object using:

    r library(Seurat) RDS<-readRDS("./demo/Demo_SP8_SP6.RDS") write.csv([e-mail],file = "./demo/Demo_SP6_SP8_metadata.csv",quote = F)

Basic Workflow

Demo data is available in the demo folder of the R package installed from GitHub. Alternatively, you can download the files directly using the following commands:

wget https://github.com/PrinceWang2018/ST_Distance/raw/master/demo/Demo_SP6_SP8_metadata.csv  
wget https://github.com/PrinceWang2018/ST_Distance/raw/master/demo/Demo_SP6_SP8_tissue_positions.csv  
wget https://github.com/PrinceWang2018/ST_Distance/raw/master/demo/Demo_SP8_SP6.RDS  

Below is a basic workflow demonstrating how to use the demo data for reference:

1. Load required packages and data

library(STDistance)
setwd("R package dir or work dir")

# Load spatial coordinates
tissue_posi <- read.csv("./demo/Demo_SP6_SP8_tissue_positions.csv", header = TRUE)

# Load metadata
metadata <- read.csv("./demo/Demo_SP6_SP8_metadata.csv", header = TRUE, row.names = 1)

2. Normalize spatial coordinates

tissue_posi_normalized <- normalize_spatial(tissue_posi)

3. Merge spatial and metadata information

posi <- merge(
  x = tissue_posi_normalized,
  y = metadata,
  by.x = "Newbarcode",
  by.y = "row.names",
  all.y = TRUE
)

4. Calculate nearest distances between cell types

distance_results <- calculate_nearest_distances(
  posi,
  reference_type = "Macrophage",
  target_types = c("Epithelial_cells_A", "Epithelial_cells_B", "Epithelial_cells_C"),
  x_col = "pxl_row_in_fullres",
  y_col = "pxl_col_in_fullres",
  id_col = "Newbarcode",
  type_col = "celltype_ABCDepi"
)

5. Compare distance among subgroups

plot_distance_boxplot(
  distance_results,
  id_col = "Newbarcode",
  show_points = TRUE,
  y_scale = "log10",
  palette = "Dark2"
)

6. Create radial network visualization

plot_radial_distance(
  distance_results,
  id_col = "Newbarcode",
  reference_type = "Macrophage",
  label_padding = 0.3,
  show_labels = TRUE,
  palette = "Dark2"
)

7. Spatial visualization of interactions

Between two cell types:

visualize_spatial_network(
  posi,
  sample = "SP8",
  reference_type = "Macrophage",
  target_type = "Epithelial_cells_A",
  x_col = "pxl_row_in_fullres",
  y_col = "pxl_col_in_fullres",
  type_col = "celltype_ABCDepi",
  color_palette = c("Macrophage" = "#90ee90", "Epithelial_cells_A" = "#377EB8"),
  alpha = 0.7
)

Between reference and multiple target types:

visualize_spatial_multinetwork(
  posi,
  sample = "SP8",
  reference_type = "Macrophage",
  target_type = c("Epithelial_cells_A", "Epithelial_cells_B"),
  type_col = "celltype_ABCDepi",
  color_palette = c("Macrophage" = "#90ee90",
                   "Epithelial_cells_A" = "#377EB8",
                   "Epithelial_cells_B" = "#E41A1C"),
  point_alpha = 0.7
)

With expression gradient:

visualize_spatial_gradient(
  spatial_data = posi,
  sample = "SP8",
  gradient_type = "Epithelial_cells_A",
  fixed_type = "Macrophage",
  expression_col = "gen2_SPLIz_numeric",
  type_col = "celltype_ABCDepi",
  fixed_color = "#CCCCCC",
  line_color = "#444444",
  gradient_palette = "viridis",
  point_size = 1.5,
  point_alpha = 0.9
)

8. Correlation analysis

result_correlation <- calculate_correlations(
  spatial_data = posi,
  distance_results = distance_results,
  spatial_feature = "gen2_SPLIz_numeric",
  distance_metric = "Epithelial_cells_A",
  method = "pearson",
  plot = TRUE,
  plot_title = "Correlation between Gene Expression and Distance"
)

print(paste("Correlation coefficient:", result_correlation$estimate))
print(paste("P-value:", result_correlation$p_value))
result_correlation$plot

Applications

STDistance can be used for various spatial transcriptomics analyses:

1. Cell-cell interaction networks: Visualize spatial relationships between different cell types
2. Immune microenvironment characterization: Study spatial organization of immune cells
3. Key gene effects on interactions: Analyze how immune checkpoint genes influence cell proximity
4. Spatial patterns and disease: Investigate associations between cell type distributions and clinical outcomes
5. Tumor microenvironment: Study spatial relationships between tumor cells and stromal components

Limitations

1. Distance is only one aspect of cell communication: While spatial proximity suggests potential interactions, true cell-cell communication should be validated with receptor-ligand analysis tools like CellChat or NicheNet that consider molecular expression profiles.
2. Resolution limitations: Current spatial transcriptomics demo have resolution limits (50μm spot size). Single-cell resolution spatial data (10xVisium HD or other poly(A) / probes captured high resolution data) will provide more accurate distance measurements and increase detection power for spatial relationships.

Troubleshooting

Common issues and solutions:

1. Missing columns error: Ensure your input files contain all required columns:
2. Spatial file: Must have coordinate columns (default "pxl_row_in_fullres" and "pxl_col_in_fullres")

3. Metadata: Must have cell type annotation column

4. No distances calculated: Check that:

5. Your reference and target cell types exist in the metadata
6. The type_col parameter correctly specifies your cell type column name

7. There are actually cells of the specified types in your sample

8. Visualization issues:

9. For crowded plots, try adjusting point_size and alpha parameters
10. For color issues, specify a custom color_palette

Citation

If you use STDistance in your research, please cite:

Wang, Z., Yang, L., Yang, S., Li, G., Xu, M., Kong, B., Shao, C., & Liu, Z. (2025). Isoform switch of CD47 provokes macrophage-mediated pyroptosis in ovarian cancer. bioRxiv, 2025.2004.2017.649282. https://doi.org/10.1101/2025.04.17.649282

Contact

For questions or issues, please contact:

• [e-mail] or [e-mail]
• GitHub issues: https://github.com/PrinceWang2018/ST_Distance/issues

License

GPL-3 © Zixiang Wang, Lei Yang, Zhaojian Liu

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(STDistance)

STDistance documentation built on June 18, 2025, 5:08 p.m.