hoodscanR
Workflows
Standard Workflow
Perform cellular neighborhood scanning, colocalization analysis, and neighborhood-based clustering on single-cell spatial transcriptomics data.
library(hoodscanR)
library(SpatialExperiment)
library(scico)
# 1. Read the input SpatialExperiment object
data("spe_test")
spe <- readHoodData(spe, anno_col = "celltypes")
# 2. Visualize cell positions and annotations
plotTissue(spe, color = cell_annotation, size = 1.5, alpha = 0.8)
# 3. Identify nearest neighbor cells
fnc <- findNearCells(spe, k = 100)
# 4. Calculate neighborhood association probabilities
pm <- scanHoods(fnc$distance)
# 5. Merge probabilities by cell type groups
hoods <- mergeByGroup(pm, fnc$cells)
# 6. Visualize neighborhood probabilities
plotHoodMat(hoods, n = 10, hm_height = 5)
# 7. Merge neighborhood results back into the SpatialExperiment object
spe <- mergeHoodSpe(spe, hoods)
# 8. Calculate neighborhood entropy and perplexity and visualize
spe <- calcMetrics(spe, pm_cols = colnames(hoods))
plotTissue(spe, size = 1.5, color = perplexity) + scale_color_scico(palette = "tokyo")
# 9. Perform neighborhood colocalization analysis
plotColocal(spe, pm_cols = colnames(hoods))
# 10. Cluster cells by neighborhood probability distribution
spe <- clustByHood(spe, pm_cols = colnames(hoods), k = 10)
# 11. Visualize cluster probability distributions and spatial clusters
plotProbDist(spe, pm_cols = colnames(hoods), by_cluster = TRUE, plot_all = TRUE, show_clusters = as.character(seq(10)))
plotTissue(spe, color = clusters)
Input/Output Note: Inputs a SpatialExperiment object with cell-type annotations; outputs an updated SpatialExperiment containing neighborhood probabilities, entropy, perplexity, and neighborhood-based cluster assignments.
When to Use
- To perform cellular neighborhood analysis on single-cell resolution spatial transcriptomics data using
SpatialExperiment objects.
- To calculate the probability of each cell associating with its spatial neighbors using
scanHoods().
- To analyze and visualize cell-type colocalization patterns across a tissue slide using
plotColocal().
- To cluster cells based on their local neighborhood composition using
clustByHood().
When NOT to Use
- For spot-based spatial transcriptomics data (e.g., 10x Visium) without single-cell resolution; use standard
SpatialExperiment workflows because hoodscanR is designed for single-cell resolution data.
- For standard non-spatial single-cell RNA-seq analysis; use
scran or Seurat because hoodscanR requires spatial coordinates (x and y).
- For cell-type deconvolution of spatial spots; use
RCTD because hoodscanR assumes cells are already annotated with cell types.
Data Requirements
- Input format: A
SpatialExperiment object.
- Structure: Must contain spatial coordinates (accessible via
spatialCoords) and cell-type annotations in colData (specified via anno_col in readHoodData()).
Key Parameters
- anno_col (NULL): Character string specifying the column name in
colData containing cell-type annotations.
- k (
100): The number of nearest neighbor cells to identify in findNearCells().
- n (
10): Number of random cells to plot in plotHoodMat().
- targetCells (NULL): Vector of specific cell IDs to plot in
plotHoodMat().
- pm_cols (NULL): Column names of the probability matrix to use for metric calculation or clustering.
Best Practices
- Format the input
SpatialExperiment object using readHoodData() to ensure compatibility with all package functions.
- Use
perplexity rather than entropy for a more intuitive measure of neighborhood mixture (e.g., perplexity of 2 indicates a 50/50 mix of two neighborhoods).
- Set
k = 100 in findNearCells() as a robust starting point for capturing local cellular neighborhoods.
- Visualize neighborhood probability distributions within each cluster using
plotProbDist() to interpret the biological meaning of the clusters.
Common Pitfalls
- Mismatched cell-type annotation column: Occurs if
anno_col is not correctly specified in readHoodData(). Fix: Verify the column name in colData(spe) and pass it exactly to readHoodData(spe, anno_col = "your_column").
- Slow neighbor search on large datasets: Occurs when searching for very large values of
k. Fix: Keep k at a reasonable size (e.g., 50 to 100) since the underlying search uses the fast Approximate Near Neighbor (ANN) algorithm.
Alternatives
Seurat: For spatial data visualization and clustering, though lacking the specific softmax-based neighborhood probability modeling.Giotto: For comprehensive spatial analysis, including neighborhood enrichment and cell-to-cell interaction.squidpy: For spatial neighbor graph analysis (Python-based).
Citations
- Liu, N. and Davis, M. (2026), hoodscanR.
References