Cell-type annotation and spatial clustering with STBench

Introduction

This vignette uses the cell-type labels already supplied in norm_example, so an external SingleR reference is not required.

data(norm_example)
norm <- norm_example
names(norm)
#> [1] "None"    "SpaNorm"

Cell-type annotation

The example data include existing cell_type annotations. We use these to demonstrate downstream comparisons without requiring an external SingleR reference. In a full analysis, run_annotation() can be used with an appropriate reference.

annotated_norm <- norm
annotation_col <- "cell_type"

Visualise spatial cell-type assignments

p_annotation <- plot_spatial_annotation(
  norm_list = annotated_norm,
  annotation_col = annotation_col,
  method_order = NULL,
  point_size = 0.5,
  ncol = 2,
  theme_name = "classic",
  palette = "turbo"
)
p_annotation$plot

Compare cell-type composition

We examine relative proportions and absolute spot counts assigned to each cell type.

p_prop <- plot_celltype_proportion(
  norm_list = annotated_norm,
  annotation_col = annotation_col,
  palette = "turbo",
  show = "proportion",
  theme_name = "classic"
)
p_prop$plot

p_count <- plot_celltype_proportion(
  norm_list = annotated_norm,
  annotation_col = annotation_col,
  show = "count",
  theme_name = "classic"
)
p_count$plot

Calculate and plot annotation agreement

Pairwise agreement measures the fraction of spots receiving the same label under two methods. It measures consistency, not accuracy against a known ground truth.

annotation_agreement <- calculate_annotation_agreement(
  norm_list = annotated_norm,
  annotation_col = annotation_col,
  remove_na = TRUE
)
annotation_agreement
#>   method1 method2 agreement n_compared
#> 1    None SpaNorm         1        944

p_agreement <- plot_annotation_agreement(
  norm_list = annotated_norm,
  annotation_col = annotation_col,
  remove_na = TRUE,
  show_values = TRUE,
  digits = 2,
  colour_option = "viridis",
  theme_name = "classic"
)
p_agreement$plot

Marker investigations

Marker comparisons depend on the presence of biologically relevant genes. The following code demonstrates how to specify candidate markers when available.

p_marker <- plot_marker_expression(
  norm_list = annotated_norm,
  markers = head(rownames(annotated_norm[[1]]), 2),
  annotation_col = "cell_type",
  palette = "turbo"
)
p_marker$plot

BANKSY spatial clustering

BANKSY incorporates spatial neighbourhood information alongside gene expression to identify spatial domains. We execute clustering on the small example dataset.

banksy_norm <- run_banksy_individual(
  norm_list = norm,
  methods = names(norm),
  assay_name = "logcounts",
  cluster_col = "banksy_cluster",
  k_geom = 15,
  lambda = 0.8,
  resolution = 0.2,
  seed = 123
)

Visualise and evaluate BANKSY clusters

These functions operate on the output of run_banksy_individual() above.

p_banksy <- plot_spatial_clustering(
  norm_list = banksy_norm,
  cluster_col = "banksy_cluster",
  ground_truth_col = "layer_guess",
  show = "both",
  methods = names(banksy_norm),
  point_size = 0.5,
  ncol = 2,
  theme_name = "classic"
)
p_banksy$plot

metrics_df <- calculate_clustering_metrics(
  norm_list = banksy_norm,
  ground_truth_col = "layer_guess",
  cluster_col = "banksy_cluster",
  methods = names(banksy_norm)
)
metrics_df
#>    method  slice   n        ARI       NMI       HOM       COM          ASW
#> 1    None slice1 944 0.08797778 0.2520017 0.1479403 0.8496386 0.0009367813
#> 2 SpaNorm slice1 944 0.08797778 0.2520017 0.1479403 0.8496386 0.0009367813
#>     Overall n_asw ASW_sampled
#> 1 0.4165269   944       FALSE
#> 2 0.4165269   944       FALSE

p_metrics <- plot_clustering_metrics(
  metrics_df = metrics_df,
  metrics = c("ARI", "NMI", "HOM", "COM", "ASW", "Overall"),
  ncol = 2,
  scales = "free_y",
  theme_name = "bw"
)
p_metrics$plot

ranking_df <- rank_normalization_methods(metrics_df = metrics_df)
ranking_df
#>   Rank  method   Overall
#> 1    1    None 0.4165269
#> 2    2 SpaNorm 0.4165269

p_ranking <- plot_normalization_ranking(
  ranking_df = ranking_df,
  bar_width = 0.7,
  label_size = 3.5,
  theme_name = "classic"
)
p_ranking$plot

BANKSY with different gene-selection strategies

For a small example dataset, a selection size of 500 can exceed the number of available genes. For the small dataset, each selection strategy uses up to the available number of genes.

data(svg_example)

banksy_genes <- run_banksy_gene_selection(
  norm_list = norm,
  svg_list = svg_example,
  gene_selection = "all",
  assay_name = "logcounts",
  k_geom = 15,
  lambda = 0.8,
  resolution = 0.2,
  seed = 123
)

metrics_genes <- calculate_gene_selection_metrics(
  banksy_list = banksy_genes,
  ground_truth_col = "layer_guess"
)

p_genes <- plot_gene_selection_metrics(
  metrics_df = metrics_genes,
  ncol = 3,
  scales = "free_y",
  theme_name = "classic"
)
p_genes$plot

Session information

sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 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] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] STBench_0.99.2 rmarkdown_2.32
#> 
#> loaded via a namespace (and not attached):
#>  [1] SummarizedExperiment_1.43.0 gtable_0.3.6               
#>  [3] rjson_0.2.23                xfun_0.62                  
#>  [5] bslib_0.12.0                ggplot2_4.0.4              
#>  [7] Biobase_2.73.2              lattice_0.23-1             
#>  [9] vctrs_0.7.3                 tools_4.6.2                
#> [11] generics_0.1.4              parallel_4.6.2             
#> [13] stats4_4.6.2                Polychrome_1.6.2           
#> [15] sccore_1.0.7                tibble_3.3.1               
#> [17] cluster_2.1.8.3             pkgconfig_2.0.3            
#> [19] Matrix_1.7-6                data.table_1.18.6.1        
#> [21] RColorBrewer_1.1-3          S7_1.0.0                   
#> [23] S4Vectors_0.51.10           sparseMatrixStats_1.25.0   
#> [25] scatterplot3d_0.3-45        lifecycle_1.0.5            
#> [27] compiler_4.6.2              farver_2.1.2               
#> [29] aricode_1.1.0               Seqinfo_1.3.2              
#> [31] htmltools_0.5.9             sys_3.4.3                  
#> [33] buildtools_1.0.0            sass_0.5.0                 
#> [35] yaml_2.3.12                 pillar_1.11.1              
#> [37] jquerylib_0.1.4             tidyr_1.3.2                
#> [39] uwot_0.2.5                  SingleCellExperiment_1.35.2
#> [41] DelayedArray_0.39.8         cachem_1.1.0               
#> [43] clevr_0.1.2                 dbscan_1.3.0               
#> [45] magick_2.9.1                viridis_0.6.5              
#> [47] mclust_6.1.4                abind_1.4-8                
#> [49] tidyselect_1.2.1            digest_0.6.39              
#> [51] dplyr_1.2.1                 purrr_1.2.2                
#> [53] maketools_1.3.2             labeling_0.4.3             
#> [55] fastmap_1.2.0               grid_4.6.2                 
#> [57] colorspace_2.1-4            cli_3.6.6                  
#> [59] SparseArray_1.13.5          magrittr_2.0.5             
#> [61] patchwork_1.3.2             leidenAlg_1.1.8            
#> [63] S4Arrays_1.13.3             withr_3.0.3                
#> [65] scales_1.4.0                XVector_0.53.0             
#> [67] matrixStats_1.5.0           igraph_2.3.4               
#> [69] otel_0.3.0                  Banksy_1.9.6               
#> [71] gridExtra_2.3.1             SpatialExperiment_1.23.0   
#> [73] evaluate_1.0.5              RcppHungarian_0.3          
#> [75] knitr_1.52                  GenomicRanges_1.65.4       
#> [77] IRanges_2.47.5              irlba_2.4.1                
#> [79] viridisLite_0.4.3           rlang_1.3.0                
#> [81] Rcpp_1.1.2                  glue_1.8.1                 
#> [83] BiocGenerics_0.59.13        jsonlite_2.0.0             
#> [85] R6_2.6.1                    MatrixGenerics_1.25.0