Package 'STDistance'

Title: Spatial Transcriptomics Distance Calculation and Visualization
Description: Analysis of spatial relationships between cell types in spatial transcriptomics data. Spatial proximity is a critical factor in cell-cell communication. The package calculates nearest neighbor distances between specified cell types and provides visualization tools to explore spatial patterns. Applications include studying cell-cell interactions, immune microenvironment characterization, and spatial organization of tissues.
Authors: Zixiang Wang [aut, cre] (ORCID: <https://orcid.org/0000-0001-5252-9764>), Lei Yang [aut], Zhaojian Liu [aut]
Maintainer: Zixiang Wang <[email protected]>
License: GPL (>= 3)
Version: 0.6.6
Built: 2026-05-12 08:33:01 UTC
Source: https://github.com/cran/STDistance

Help Index

Perform correlation analysis between spatial features and distance metrics with visualization

Description

Perform correlation analysis between spatial features and distance metrics with visualization

Usage

calculate_correlations(
  spatial_data,
  distance_results,
  spatial_feature,
  distance_metric,
  method = "pearson",
  plot = TRUE,
  plot_title = NULL
)

Arguments

spatial_data

Spatial data containing feature columns and Newbarcode identifier
distance_results

Distance results containing distance metrics and Newbarcode identifier
spatial_feature

Column name from spatial_data to use for correlation (e.g., "gen2_SPLIz_numeric")
distance_metric

Column name from distance_results to use for correlation (e.g., "Epithelial_cells_A")
method

Correlation method ("pearson", "spearman", "kendall")
plot

Logical, whether to generate a scatter plot
plot_title

Title for the scatter plot (optional)

Value

A list containing correlation results and ggplot object (if plot=TRUE)

Examples

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")

Calculate nearest distances between cell types

Description

Calculate nearest distances between cell types

Usage

calculate_nearest_distances(
  spatial_data,
  reference_type,
  target_types,
  x_col = "pxl_row_in_fullres",
  y_col = "pxl_col_in_fullres",
  id_col = "barcode",
  type_col = "Epi_strom"
)

Arguments

spatial_data

A data frame containing spatial coordinates and cell type info
reference_type

The reference cell type to calculate distances from
target_types

Vector of target cell types to calculate distances to
x_col

Column name for x-coordinates
y_col

Column name for y-coordinates
id_col

Column name for cell identifiers
type_col

Column name for cell type information

Value

A data frame with nearest distances for each reference cell

Examples

calculate_nearest_distances(posi, reference_type="Macrophage",
                 target_types=c("Epithelial_cells_A","Epithelial_cells_B",
                 "Epithelial_cells_C","Epithelial_cells_D"),
                 id_col = "Newbarcode",
                 type_col = "celltype_ABCDepi")

distance_results

Description

A data frame with nearest distances for each reference cell

Usage

data("distance_results")

Format

A data frame with 18 observations on the following 5 variables.

Newbarcode

a character vector

Epithelial_cells_A

a numeric vector

Epithelial_cells_B

a numeric vector

Epithelial_cells_C

a numeric vector

Epithelial_cells_D

a numeric vector

Details

A data frame with nearest distances for each reference cell.

Source

This study.

References

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

Examples

data(distance_results)
## maybe str(distance_results) ; plot(distance_results) ...

Metadata

Description

Metadata of a Seurat Object.

Usage

data("metadata")

Format

A data frame with 293 observations on the following 9 variables.

orig.ident

a character vector

nCount_Spatial

a numeric vector

nFeature_Spatial

a numeric vector

nCount_SCT

a numeric vector

nFeature_SCT

a numeric vector

integrated_snn_res.0.8

a numeric vector

seurat_clusters

a numeric vector

celltype_ABCDepi

a character vector

gen2_SPLIz_numeric

a numeric vector

Details

Metadata dataframe can be exported from Seurat Object as follows. The Seurat Object should be fully annotated and the metadata dataframe should included: orig.ident, celltype, the target gene expression, splicing index (SpliZ), etc.

Source

This study.

References

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

Examples

data(metadata)
## maybe str(metadata) ; plot(metadata) ...

Normalize spatial coordinates

Description

Normalize spatial coordinates

Usage

normalize_spatial(
  data,
  sample_col = "Sample",
  x_col = "pxl_row_in_fullres",
  y_col = "pxl_col_in_fullres",
  min_value = 1,
  max_value = 10000
)

Arguments

data

A data frame containing spatial coordinates
sample_col

Column name specifying sample IDs
x_col

Column name for x-coordinates
y_col

Column name for y-coordinates
min_value

Minimum value for normalization range
max_value

Maximum value for normalization range

Value

A data frame with normalized coordinates

Examples

tissue_posi_normalized<-normalize_spatial(tissue_posi)

Visualize Nearest Neighbor Distances with Boxplot and Mean ± SEM

Description

Creates a boxplot visualization of distance metrics with overlaid mean points and SEM error bars. Suitable for comparing multiple groups with potentially skewed distributions.

Usage

plot_distance_boxplot(
  distance_result,
  id_col = "barcode",
  show_points = FALSE,
  y_scale = c("original", "log10"),
  palette = "Set2"
)

Arguments

distance_result

A data.frame generated by calculate_nearest_distances(), containing distance measurements with columns: id_col + target_types.
id_col

Name of the column containing cell IDs (default: "barcode").
show_points

Logical, whether to overlay individual data points (default: FALSE).
y_scale

Method for y-axis scaling: "original" or "log10" (default: "original").
palette

Color palette name from RColorBrewer (default: "Set2").

Value

A ggplot2 object. Additional customization can be done using ggplot2 functions.

Examples

plot_distance_boxplot(distance_results,id_col = "Newbarcode")

Radial Distance Visualization with Collision Avoidance

Description

Creates a radial plot with automatic label placement to prevent overlaps between nodes and text labels.

Usage

plot_radial_distance(
  distance_result,
  reference_type,
  id_col = "barcode",
  scale_radius = 1,
  show_labels = TRUE,
  palette = "Set2",
  label_padding = 0.15,
  center_label_expansion = 1.5
)

Arguments

distance_result

Data.frame from calculate_nearest_distances()
reference_type

Name of the reference cell type (center node)
id_col

Name of ID column (default: "barcode")
scale_radius

Scaling factor for layout (default: 1)
show_labels

Whether to show distance labels (default: TRUE)
palette

Color palette name (default: "Set2")
label_padding

Radial padding for labels (default: 0.15)
center_label_expansion

Center expansion for labels (default: 1.5)

Value

A ggplot2 object

Examples

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

posi

Description

Merged spatial location and metadata information.

Usage

data("posi")

Format

A data frame with 293 observations on the following 18 variables.

Newbarcode

a character vector

barcode

a character vector

in_tissue

a numeric vector

array_row

a numeric vector

array_col

a numeric vector

pxl_row_in_fullres

a numeric vector

pxl_col_in_fullres

a numeric vector

Sample

a character vector

Sampleid

a numeric vector

orig.ident

a character vector

nCount_Spatial

a numeric vector

nFeature_Spatial

a numeric vector

nCount_SCT

a numeric vector

nFeature_SCT

a numeric vector

integrated_snn_res.0.8

a numeric vector

seurat_clusters

a numeric vector

celltype_ABCDepi

a character vector

gen2_SPLIz_numeric

a numeric vector

Details

Merged spatial location and metadata information.

Source

This study.

References

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

Examples

data(posi)
## maybe str(posi) ; plot(posi) ...

tissue_posi

Description

Position of the spots from spatial transcriptome data.

Usage

data("tissue_posi")

Format

A data frame with 9984 observations on the following 9 variables.

barcode

a character vector

in_tissue

a numeric vector

array_row

a numeric vector

array_col

a numeric vector

pxl_row_in_fullres

a numeric vector

pxl_col_in_fullres

a numeric vector

Sample

a character vector

Sampleid

a numeric vector

Newbarcode

a character vector

Details

Please find the tissue_positions.csv from the spaceranger output files: ./out/spatial/tissue_positions.csv Multiple samples should be merged together, adding "samples" and "Newbarcode" columns.

Source

This study.

References

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

Examples

data(tissue_posi)
## maybe str(tissue_posi) ; plot(tissue_posi) ...

tissue_posi_normalized

Description

Normalized tissue spots position.

Usage

data("tissue_posi_normalized")

Format

A data frame with 9984 observations on the following 9 variables.

barcode

a character vector

in_tissue

a numeric vector

array_row

a numeric vector

array_col

a numeric vector

pxl_row_in_fullres

a numeric vector

pxl_col_in_fullres

a numeric vector

Sample

a character vector

Sampleid

a numeric vector

Newbarcode

a character vector

Details

Normalized tissue spots position.

Source

This study.

References

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

Examples

data(tissue_posi_normalized)
## maybe str(tissue_posi_normalized) ; plot(tissue_posi_normalized) ...

Visualize spatial network with expression gradient

Description

Visualize spatial network with expression gradient

Usage

visualize_spatial_gradient(
  spatial_data,
  sample,
  gradient_type,
  fixed_type,
  expression_col = "gen2_SPLIz_numeric",
  x_col = "pxl_row_in_fullres",
  y_col = "pxl_col_in_fullres",
  type_col = "Epi_strom",
  fixed_color = "#A9C6D9",
  line_color = "#666666",
  gradient_palette = "C",
  point_size = 1,
  point_alpha = 0.8,
  line_width = 0.3,
  line_alpha = 0.6,
  show_legend = TRUE,
  legend_title = "Expression",
  grid_major_color = "gray90",
  grid_minor_color = "gray95",
  border_color = "black",
  background_color = "white"
)

Arguments

spatial_data

Spatial coordinates data frame containing cell types and expression values
sample

Sample name in the spatial transcriptome data
gradient_type

Cell type to show with expression gradient coloring
fixed_type

Cell type to show in fixed color (default gray)
expression_col

Column name containing expression values (default "gen2_SPLIz_numeric")
x_col

Column name for x-coordinates (default "pxl_row_in_fullres")
y_col

Column name for y-coordinates (default "pxl_col_in_fullres")
type_col

Column name for cell type information (default "Epi_strom")
fixed_color

Color for the fixed cell type (default "#A9C6D9" - light gray-blue)
line_color

Color for connection lines (default "#666666" - dark gray)
gradient_palette

Color palette for expression gradient (default viridis option "C")
point_size

Size of points (default 1)
point_alpha

Transparency of points (default 0.8)
line_width

Width of connection lines (default 0.3)
line_alpha

Transparency of connection lines (default 0.6)
show_legend

Logical whether to show legend (default TRUE)
legend_title

Title for the legend (default "Expression")
grid_major_color

Color for major grid lines (default "gray90")
grid_minor_color

Color for minor grid lines (default "gray95")
border_color

Color for plot border (default "black")
background_color

Color for plot background (default "white")

Value

A ggplot object showing the spatial relationships with expression gradient

Examples

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",
                           legend_title = "Expression",
                           background_color = "white")

Visualize spatial relationships between multiple cell types

Description

Visualize spatial relationships between multiple cell types

Usage

visualize_spatial_multinetwork(
  spatial_data,
  sample,
  reference_type,
  target_types,
  x_col = "pxl_row_in_fullres",
  y_col = "pxl_col_in_fullres",
  type_col = "Epi_strom",
  color_palette = NULL,
  point_alpha = 0.7,
  line_alpha = 0.5,
  point_size = 1.5,
  line_width = 0.3,
  show_legend = TRUE
)

Arguments

spatial_data

Spatial coordinates data frame
sample

Sample name in the spatial transcriptome data
reference_type

Reference cell type (character vector of length 1)
target_types

Target cell type(s) (character vector of 1 or more)
x_col

Column name for x-coordinates
y_col

Column name for y-coordinates
type_col

Column name for cell type information
color_palette

Named vector of colors for cell types
point_alpha

Transparency level for points
line_alpha

Transparency level for connection lines
point_size

Size of points in plot
line_width

Width of connection lines
show_legend

Logical, whether to show legend

Value

A ggplot object showing the spatial relationships

Examples

visualize_spatial_multinetwork(posi, sample="SP8",reference_type="Macrophage",
                     target_type=c("Epithelial_cells_A","Epithelial_cells_B"),
                     type_col = "celltype_ABCDepi")

Visualize spatial relationships between cell types

Description

Visualize spatial relationships between cell types

Usage

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

Arguments

spatial_data

Spatial coordinates data frame
sample

Sample name in the spatial transcriptome data
reference_type

Reference cell type
target_type

Target cell type
x_col

Column name for x-coordinates
y_col

Column name for y-coordinates
type_col

Column name for cell type information
color_palette

Named vector of colors for cell types
alpha

Transparency level for points and lines

Value

A ggplot object showing the spatial relationships

Examples

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"))