Skip to contents

Spacelink Package Overview

Source: vignettes/overview.Rmd
overview.Rmd

The spacelink package consists of two main functions:

  • spacelink: Performs hypothesis testing at the global tissue level to identify spatially variable genes (SVGs) using an adaptive multi-kernel approach. It also provides Effective Spatial Variability (ESV) scores (0-1), where higher values indicate stronger spatial variability in gene expression.
  • spacelink_ctSVG: Performs hypothesis testing to identify cell-type–specific spatially variable genes (ctSVGs) using a data-driven colocalization gating strategy. It reports cell-type–specific Effective Spatial Variability (ct-ESV) scores (ranging from 0 to 1), where higher values indicate stronger spatial variability within the focal cell type.

1. spacelink - Global Analysis

Inputs

spacelink requires two primary inputs:

  • normalized_counts: Log-transformed normalized count matrix (genes x spots). This can be generated, for example, by applying normalization methods such as SCTransform to raw count data. See the CosMx and Visium application examples for normalization details.
  • spatial_coords: Two-dimensional spatial coordinate matrix (spots x 2).

Optionally, you can provide:

  • lite: Logical variable. If TRUE, a grid-based approximation is used to speed up computation for large datasets. Default is FALSE. For very large datasets, we recommend setting lite = TRUE.
  • grid_size: Grid cell size when lite = TRUE. If NULL, It is set automatically to 5 times the minimum nearest-neighbor distance. Default is NULL. We recommend adjusting the grid size to suit your dataset.
  • n_workers: Number of workers for parallel computation across genes.

Outputs

  • pval : Combined p-value testing whether each gene is spatially variable.
  • padj : Benjamini-Hochberg adjusted p-value.
  • ESV : Effective Spatial Variability score (0–1) for prioritizing SVGs; higher values indicate stronger spatial variability.
  • ESV_adj : ESV adjusted for non-SVGs (set to 0 if padj > 0.05).

Code example 

global_results <- spacelink(
  normalized_counts = normalized_expression_matrix,
  spatial_coords = coordinates,
  lite = FALSE,
  n_workers = 1
)

# View results
head(global_results[order(global_results$ESV_adj, decreasing=T), c("pval","padj","ESV","ESV_adj")])

2. spacelink_ctSVG - Cell-Type-Specific Analysis

Inputs

spacelink_ctSVG requires four primary inputs:

  • normalized_counts: Log-transformed normalized count matrix (as above).
  • spatial_coords: Two-dimensional spatial coordinate matrix (spots x 2).
  • cell_type_proportions: Cell type proportion matrix (spots x cell-types), e.g., estimated with RCTD. If all spots contain only one cell type (no mixing), spacelink is applied internally to the subset of spots corresponding to the focal cell type.
  • focal_cell_type: Name of the focal cell type; must match one of the columns in cell_type_proportions.

Optionally, you can provide:

  • lite: Logical variable, applicable only when all spots are pure (single-cell resolution). If TRUE, a grid-based approximation is used to speed up computation for large datasets. Default is FALSE. For very large numbers of cells, we recommend setting lite = TRUE.
  • grid_size: Grid cell size when lite = TRUE. If NULL, set automatically to 5 times the minimum nearest-neighbor distance. Default is NULL. Adjust to suit your dataset.
  • n_workers: Number of workers for parallel computation across genes.

Outputs

  • pval : Combined p-value testing spatial variability within the focal cell type.
  • padj : Benjamini-Hochberg adjusted p-value.
  • ESV : Cell-type–specific Effective Spatial Variability (ct-ESV) score (0–1) for prioritizing ctSVGs; higher values indicate stronger spatial variability within the focal cell type.
  • ESV_adj : ESV adjusted for non-ctSVGs (set to 0 if padj > 0.05).

Code example 

cell_type_results <- spacelink_ctSVG(
  normalized_counts = normalized_expression_matrix,
  spatial_coords = coordinates,
  cell_type_proportions = cell_type_proportions,
  focal_cell_type = cell_type_name,
  lite = FALSE,
  n_workers = 1
)

# View results
head(cell_type_results[order(cell_type_results$ESV_adj, decreasing=T), c("pval","padj","ESV","ESV_adj")])